@opendata-ai/openchart-vanilla 2.12.1 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-vanilla",
-  "version": "2.12.1",
+  "version": "2.13.0",
   "description": "Vanilla JS renderer for openchart: SVG charts, HTML tables, force-directed graphs",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -50,8 +50,8 @@
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.6",
-    "@opendata-ai/openchart-core": "2.12.1",
-    "@opendata-ai/openchart-engine": "2.12.1",
+    "@opendata-ai/openchart-core": "2.13.0",
+    "@opendata-ai/openchart-engine": "2.13.0",
     "d3-force": "^3.0.0",
     "d3-quadtree": "^3.0.1"
   },

package/src/__tests__/export.test.ts

@@ -1,8 +1,9 @@
 /**
  * Export utility tests.
  *
- * Tests exportSVG, exportCSV, and exportJPG functions directly, verifying SVG string
- * validity, CSV formatting with headers and proper escaping, and JPG export interface.
+ * Tests exportSVG, exportSVGWithFonts, exportCSV, exportPNG, and exportJPG
+ * functions directly, verifying SVG string validity, font embedding,
+ * dimension parsing, CSV formatting, and raster export interfaces.
  */
 
 import type { CompileOptions } from '@opendata-ai/openchart-engine';
@@ -10,7 +11,7 @@ import { compileChart } from '@opendata-ai/openchart-engine';
 import { afterEach, describe, expect, it } from 'vitest';
 import { createContainer } from '../__test-fixtures__/dom';
 import { barSpec, lineSpec } from '../__test-fixtures__/specs';
-import { exportCSV, exportJPG, exportSVG } from '../export';
+import { exportCSV, exportJPG, exportPNG, exportSVG, exportSVGWithFonts } from '../export';
 import { renderChartSVG } from '../svg-renderer';
 
 // ---------------------------------------------------------------------------
@@ -76,6 +77,57 @@ describe('exportSVG', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// exportSVGWithFonts
+// ---------------------------------------------------------------------------
+
+describe('exportSVGWithFonts', () => {
+  it('returns a promise', () => {
+    const svg = renderToSVG();
+    const result = exportSVGWithFonts(svg);
+    expect(result).toBeInstanceOf(Promise);
+  });
+
+  it('resolves to a valid SVG string', async () => {
+    const svg = renderToSVG();
+    const result = await exportSVGWithFonts(svg);
+    expect(result.startsWith('<svg')).toBe(true);
+    expect(result.endsWith('</svg>')).toBe(true);
+  });
+
+  it('skips font embedding when embedFonts is false', async () => {
+    const svg = renderToSVG();
+    const result = await exportSVGWithFonts(svg, { embedFonts: false });
+    // Should not contain @font-face (no stylesheets in test env anyway)
+    expect(result).not.toContain('@font-face');
+  });
+
+  it('produces valid SVG even without stylesheets in the document', async () => {
+    const svg = renderToSVG();
+    // In test env, no Google Fonts stylesheets exist, so font collection
+    // should gracefully return nothing and the export should still work
+    const result = await exportSVGWithFonts(svg);
+    expect(result).toContain('viewBox="0 0 600 400"');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Dimension parsing (via exportPNG which uses getSVGDimensions internally)
+// ---------------------------------------------------------------------------
+
+describe('dimension parsing', () => {
+  it('exportPNG reads dimensions from viewBox when width/height are absent', () => {
+    const svg = renderToSVG();
+    // Verify the SVG has viewBox but no explicit width/height
+    expect(svg.getAttribute('viewBox')).toBe('0 0 600 400');
+    expect(svg.getAttribute('width')).toBeNull();
+    // exportPNG should still work (not fall back to 600x400 by accident)
+    const result = exportPNG(svg, { dpi: 1, embedFonts: false });
+    expect(result).toBeInstanceOf(Promise);
+    result.catch(() => {}); // happy-dom canvas limitations
+  });
+});
+
 // ---------------------------------------------------------------------------
 // exportCSV
 // ---------------------------------------------------------------------------
@@ -149,6 +201,19 @@ describe('exportCSV', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// exportPNG
+// ---------------------------------------------------------------------------
+
+describe('exportPNG', () => {
+  it('returns a Promise when called with a rendered SVG element', () => {
+    const svg = renderToSVG();
+    const result = exportPNG(svg, { embedFonts: false });
+    expect(result).toBeInstanceOf(Promise);
+    result.catch(() => {});
+  });
+});
+
 // ---------------------------------------------------------------------------
 // exportJPG
 // ---------------------------------------------------------------------------
@@ -161,7 +226,7 @@ describe('exportJPG', () => {
 
   it('returns a Promise when called with a rendered SVG element', () => {
     const svg = renderToSVG();
-    const result = exportJPG(svg);
+    const result = exportJPG(svg, { embedFonts: false });
     expect(result).toBeInstanceOf(Promise);
     // Clean up: catch any rejection from happy-dom canvas limitations
     result.catch(() => {});
@@ -169,7 +234,7 @@ describe('exportJPG', () => {
 
   it('accepts quality option between 0 and 1', () => {
     const svg = renderToSVG();
-    const result = exportJPG(svg, { quality: 0.5, dpi: 1 });
+    const result = exportJPG(svg, { quality: 0.5, dpi: 1, embedFonts: false });
     expect(result).toBeInstanceOf(Promise);
     result.catch(() => {});
   });

package/src/export.ts

@@ -1,11 +1,249 @@
 /**
- * Export utilities: serialize charts to SVG, PNG, or CSV.
+ * Export utilities: serialize charts to SVG, PNG, JPG, or CSV.
  *
  * - SVG: serializes the rendered DOM element via XMLSerializer
+ * - SVG with fonts: async version that embeds @font-face data URIs
  * - PNG: renders SVG to canvas, then extracts as Blob
+ * - JPG: same as PNG but with JPEG compression and background fill
  * - CSV: converts a data array to comma-separated text
  */
 
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SVGExportOptions {
+  /** Embed fonts as base64 data URIs in the SVG. Defaults to true. */
+  embedFonts?: boolean;
+}
+
+export interface PNGExportOptions extends SVGExportOptions {
+  /** DPI scaling factor. Defaults to 2 for retina-quality output. */
+  dpi?: number;
+}
+
+export interface JPGExportOptions extends PNGExportOptions {
+  /** JPEG quality from 0 to 1. Defaults to 0.92. */
+  quality?: number;
+}
+
+interface FontFaceData {
+  family: string;
+  weight: string;
+  style: string;
+  base64: string;
+  format: string;
+}
+
+// ---------------------------------------------------------------------------
+// Dimension parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract dimensions from an SVG element, trying width/height attributes
+ * first, then falling back to viewBox.
+ */
+function getSVGDimensions(svg: SVGElement): { width: number; height: number } {
+  const w = parseFloat(svg.getAttribute('width') || '');
+  const h = parseFloat(svg.getAttribute('height') || '');
+  if (w && h) return { width: w, height: h };
+
+  const vb = svg.getAttribute('viewBox');
+  if (vb) {
+    const parts = vb.split(/[\s,]+/).map(Number);
+    if (parts.length >= 4 && parts[2] && parts[3]) {
+      return { width: parts[2], height: parts[3] };
+    }
+  }
+
+  return { width: 600, height: 400 };
+}
+
+// ---------------------------------------------------------------------------
+// Font embedding
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect unique font-family + font-weight combos from all <text> elements.
+ */
+function collectUsedFonts(svgElement: SVGElement): Map<string, Set<string>> {
+  const fonts = new Map<string, Set<string>>();
+  const textElements = svgElement.querySelectorAll('text');
+
+  for (const el of textElements) {
+    const family = el.getAttribute('font-family');
+    const weight = el.getAttribute('font-weight') || '400';
+    if (family) {
+      // Take the first font in the stack (e.g., "Inter, sans-serif" → "Inter")
+      const primary = family.split(',')[0].trim().replace(/["']/g, '');
+      if (!fonts.has(primary)) fonts.set(primary, new Set());
+      fonts.get(primary)!.add(String(weight));
+    }
+  }
+
+  return fonts;
+}
+
+/**
+ * Find @font-face rules in document stylesheets that match the requested fonts.
+ * Returns the src URLs for .woff2 files.
+ */
+function findFontFaceRules(
+  usedFonts: Map<string, Set<string>>,
+): Array<{ family: string; weight: string; style: string; url: string; format: string }> {
+  const results: Array<{
+    family: string;
+    weight: string;
+    style: string;
+    url: string;
+    format: string;
+  }> = [];
+
+  try {
+    for (const sheet of document.styleSheets) {
+      let rules: CSSRuleList;
+      try {
+        rules = sheet.cssRules;
+      } catch {
+        // Cross-origin stylesheet, skip
+        continue;
+      }
+
+      for (const rule of rules) {
+        if (!(rule instanceof CSSFontFaceRule)) continue;
+
+        const familyRaw = rule.style.getPropertyValue('font-family').replace(/["']/g, '').trim();
+        const weight = rule.style.getPropertyValue('font-weight') || '400';
+        const style = rule.style.getPropertyValue('font-style') || 'normal';
+        const src = rule.style.getPropertyValue('src');
+
+        const weights = usedFonts.get(familyRaw);
+        if (!weights) continue;
+
+        // Check if this weight is used (handle ranges like "100 900")
+        const weightMatch = weights.has(weight) || weight.includes(' ');
+        if (!weightMatch) continue;
+
+        // Extract woff2 URL from src descriptor
+        const woff2Match = src.match(/url\(["']?([^"')]+\.woff2[^"')]*?)["']?\)/);
+        if (woff2Match) {
+          results.push({
+            family: familyRaw,
+            weight,
+            style,
+            url: woff2Match[1],
+            format: 'woff2',
+          });
+        }
+      }
+    }
+  } catch {
+    // Stylesheet access failed entirely, return empty
+  }
+
+  return results;
+}
+
+/**
+ * Fetch font files and convert to base64 data URIs.
+ */
+async function fetchFontsAsBase64(
+  fontRules: Array<{ family: string; weight: string; style: string; url: string; format: string }>,
+): Promise<FontFaceData[]> {
+  const results: FontFaceData[] = [];
+
+  const fetches = fontRules.map(async (rule) => {
+    try {
+      const response = await fetch(rule.url);
+      if (!response.ok) return;
+      const buffer = await response.arrayBuffer();
+      const base64 = arrayBufferToBase64(buffer);
+      results.push({
+        family: rule.family,
+        weight: rule.weight,
+        style: rule.style,
+        base64,
+        format: rule.format,
+      });
+    } catch {
+      // Font fetch failed (CORS, network, etc.) - skip this font
+    }
+  });
+
+  await Promise.all(fetches);
+  return results;
+}
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  let binary = '';
+  const bytes = new Uint8Array(buffer);
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Inject @font-face rules with base64 data URIs into the SVG's <defs>.
+ */
+function injectFontsIntoSVG(svgElement: SVGElement, fonts: FontFaceData[]): void {
+  if (fonts.length === 0) return;
+
+  const cssRules = fonts
+    .map(
+      (f) =>
+        `@font-face { font-family: '${f.family}'; font-weight: ${f.weight}; font-style: ${f.style}; src: url(data:font/${f.format};base64,${f.base64}) format('${f.format}'); }`,
+    )
+    .join('\n');
+
+  const ns = 'http://www.w3.org/2000/svg';
+  let defs = svgElement.querySelector('defs');
+  if (!defs) {
+    defs = document.createElementNS(ns, 'defs');
+    svgElement.insertBefore(defs, svgElement.firstChild);
+  }
+
+  const styleEl = document.createElementNS(ns, 'style');
+  styleEl.textContent = cssRules;
+  defs.insertBefore(styleEl, defs.firstChild);
+}
+
+/**
+ * Embed fonts into an SVG element by finding matching @font-face rules
+ * in the page's stylesheets, fetching the font files, and injecting
+ * them as base64 data URIs.
+ *
+ * Modifies the SVG element in place. Call this before serialization.
+ * If font fetching fails for any font, that font is silently skipped
+ * and the export proceeds with system font fallback for that face.
+ */
+async function embedFonts(svgElement: SVGElement): Promise<void> {
+  const usedFonts = collectUsedFonts(svgElement);
+  if (usedFonts.size === 0) return;
+
+  const fontRules = findFontFaceRules(usedFonts);
+  if (fontRules.length === 0) return;
+
+  const fontData = await fetchFontsAsBase64(fontRules);
+  injectFontsIntoSVG(svgElement, fontData);
+}
+
+// ---------------------------------------------------------------------------
+// SVG background color
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the chart's background color from its first rect element.
+ */
+function getSVGBackgroundColor(svgElement: SVGElement): string {
+  const firstRect = svgElement.querySelector('rect');
+  return firstRect?.getAttribute('fill') || '#ffffff';
+}
+
+// ---------------------------------------------------------------------------
+// SVG export
+// ---------------------------------------------------------------------------
+
 /**
  * Serialize an SVG element to an XML string.
  *
@@ -17,24 +255,53 @@ export function exportSVG(svgElement: SVGElement): string {
   return serializer.serializeToString(svgElement);
 }
 
-export interface PNGExportOptions {
-  /** DPI scaling factor. Defaults to 2 for retina-quality output. */
-  dpi?: number;
+/**
+ * Serialize an SVG element with embedded fonts to an XML string.
+ *
+ * Collects font-family declarations from the SVG's text elements,
+ * finds matching @font-face rules in the page's stylesheets, fetches
+ * the font files, and embeds them as base64 data URIs. The resulting
+ * SVG is self-contained and renders correctly without external fonts.
+ *
+ * @param svgElement - The rendered SVG element to serialize.
+ * @param options - Export options.
+ * @returns A Promise resolving to the SVG markup as a string.
+ */
+export async function exportSVGWithFonts(
+  svgElement: SVGElement,
+  options?: SVGExportOptions,
+): Promise<string> {
+  const shouldEmbed = options?.embedFonts ?? true;
+  if (shouldEmbed) {
+    await embedFonts(svgElement);
+  }
+  return exportSVG(svgElement);
 }
 
+// ---------------------------------------------------------------------------
+// Raster export (PNG / JPG)
+// ---------------------------------------------------------------------------
+
 /**
  * Render an SVG element to a PNG Blob via a canvas.
  *
+ * Embeds fonts by default so the exported image matches on-screen rendering.
+ * Set `embedFonts: false` to skip font embedding for faster exports.
+ *
  * @param svgElement - The rendered SVG element.
- * @param options - Optional DPI scaling.
+ * @param options - Optional DPI scaling and font embedding.
  * @returns A Promise resolving to the PNG Blob.
  */
 export async function exportPNG(svgElement: SVGElement, options?: PNGExportOptions): Promise<Blob> {
   const dpi = options?.dpi ?? 2;
-  const svgString = exportSVG(svgElement);
+  const shouldEmbed = options?.embedFonts ?? true;
+
+  if (shouldEmbed) {
+    await embedFonts(svgElement);
+  }
 
-  const width = parseFloat(svgElement.getAttribute('width') || '600');
-  const height = parseFloat(svgElement.getAttribute('height') || '400');
+  const svgString = exportSVG(svgElement);
+  const { width, height } = getSVGDimensions(svgElement);
 
   const canvas = document.createElement('canvas');
   canvas.width = width * dpi;
@@ -74,29 +341,28 @@ export async function exportPNG(svgElement: SVGElement, options?: PNGExportOptio
   });
 }
 
-export interface JPGExportOptions extends PNGExportOptions {
-  /** JPEG quality from 0 to 1. Defaults to 0.92. */
-  quality?: number;
-}
-
 /**
  * Render an SVG element to a JPEG Blob via a canvas.
  *
  * Same pipeline as exportPNG but outputs JPEG with configurable quality.
- * The canvas is filled with white before drawing to avoid transparent
- * backgrounds rendering as black in JPEG format.
+ * The canvas is filled with the chart's background color before drawing
+ * to avoid transparent backgrounds rendering as black in JPEG format.
  *
  * @param svgElement - The rendered SVG element.
- * @param options - Optional DPI scaling and JPEG quality.
+ * @param options - Optional DPI scaling, JPEG quality, and font embedding.
  * @returns A Promise resolving to the JPEG Blob.
  */
 export async function exportJPG(svgElement: SVGElement, options?: JPGExportOptions): Promise<Blob> {
   const dpi = options?.dpi ?? 2;
   const quality = options?.quality ?? 0.92;
-  const svgString = exportSVG(svgElement);
+  const shouldEmbed = options?.embedFonts ?? true;
+
+  if (shouldEmbed) {
+    await embedFonts(svgElement);
+  }
 
-  const width = parseFloat(svgElement.getAttribute('width') || '600');
-  const height = parseFloat(svgElement.getAttribute('height') || '400');
+  const svgString = exportSVG(svgElement);
+  const { width, height } = getSVGDimensions(svgElement);
 
   const canvas = document.createElement('canvas');
   canvas.width = width * dpi;
@@ -107,8 +373,8 @@ export async function exportJPG(svgElement: SVGElement, options?: JPGExportOptio
     throw new Error('Canvas 2D context not available');
   }
 
-  // Fill white background since JPEG doesn't support transparency
-  ctx.fillStyle = '#ffffff';
+  // Fill with the chart's actual background color (not hardcoded white)
+  ctx.fillStyle = getSVGBackgroundColor(svgElement);
   ctx.fillRect(0, 0, canvas.width, canvas.height);
 
   ctx.scale(dpi, dpi);
@@ -144,6 +410,10 @@ export async function exportJPG(svgElement: SVGElement, options?: JPGExportOptio
   });
 }
 
+// ---------------------------------------------------------------------------
+// CSV export
+// ---------------------------------------------------------------------------
+
 /**
  * Convert an array of data objects to a CSV string.
  *

package/src/index.ts

@@ -17,9 +17,9 @@ export type {
   TableSpec,
   VizSpec,
 } from '@opendata-ai/openchart-engine';
-export type { JPGExportOptions, PNGExportOptions } from './export';
+export type { JPGExportOptions, PNGExportOptions, SVGExportOptions } from './export';
 // Export utilities
-export { exportCSV, exportJPG, exportPNG, exportSVG } from './export';
+export { exportCSV, exportJPG, exportPNG, exportSVG, exportSVGWithFonts } from './export';
 // Graph simulation worker
 export { createSimulationWorker } from './graph/simulation-worker-url';
 export type { GraphInstance, GraphMountOptions } from './graph-mount';

package/src/mount.ts

@@ -26,7 +26,15 @@ import type {
   TooltipContent,
 } from '@opendata-ai/openchart-core';
 import { compileChart } from '@opendata-ai/openchart-engine';
-import { exportCSV, exportJPG, exportPNG, exportSVG, type JPGExportOptions } from './export';
+import {
+  exportCSV,
+  exportJPG,
+  exportPNG,
+  exportSVG,
+  exportSVGWithFonts,
+  type JPGExportOptions,
+  type SVGExportOptions,
+} from './export';
 import { observeResize } from './resize-observer';
 import { renderChartSVG } from './svg-renderer';
 import { createTooltipManager, type TooltipManager } from './tooltip';
@@ -57,10 +65,14 @@ export interface ChartInstance {
   resize(): void;
   /** Export the chart. */
   export(format: 'svg'): string;
+  export(format: 'svg-with-fonts', options?: SVGExportOptions): Promise<string>;
   export(format: 'png', options?: ExportOptions): Promise<Blob>;
   export(format: 'jpg', options?: ExportOptions): Promise<Blob>;
   export(format: 'csv'): string;
-  export(format: 'svg' | 'png' | 'jpg' | 'csv', options?: ExportOptions): string | Promise<Blob>;
+  export(
+    format: 'svg' | 'svg-with-fonts' | 'png' | 'jpg' | 'csv',
+    options?: ExportOptions,
+  ): string | Promise<Blob> | Promise<string>;
   /** Remove all DOM elements and disconnect observers. */
   destroy(): void;
   /** The current compiled layout (for hooks / debugging). */
@@ -1571,13 +1583,14 @@ export function createChart(
   }
 
   function doExport(format: 'svg'): string;
+  function doExport(format: 'svg-with-fonts', exportOptions?: SVGExportOptions): Promise<string>;
   function doExport(format: 'png', exportOptions?: ExportOptions): Promise<Blob>;
   function doExport(format: 'jpg', exportOptions?: ExportOptions): Promise<Blob>;
   function doExport(format: 'csv'): string;
   function doExport(
-    format: 'svg' | 'png' | 'jpg' | 'csv',
+    format: 'svg' | 'svg-with-fonts' | 'png' | 'jpg' | 'csv',
     exportOptions?: ExportOptions,
-  ): string | Promise<Blob> {
+  ): string | Promise<Blob> | Promise<string> {
     if (!svgElement) {
       throw new Error('Chart is not rendered yet');
     }
@@ -1585,6 +1598,8 @@ export function createChart(
     switch (format) {
       case 'svg':
         return exportSVG(svgElement);
+      case 'svg-with-fonts':
+        return exportSVGWithFonts(svgElement, exportOptions);
       case 'png':
         return exportPNG(svgElement, exportOptions);
       case 'jpg':