@internetstiftelsen/charts 0.4.1 → 0.4.3

package/README.md

@@ -43,6 +43,20 @@ chart
 chart.render('#chart-container');
 ```
 
+## Export
+
+`chart.export()` supports `svg`, `json`, `csv`, `xlsx`, `png`, `jpg`, and `pdf`.
+
+```javascript
+await chart.export('png', { download: true });
+await chart.export('csv', { download: true, delimiter: ';' });
+await chart.export('xlsx', { download: true, sheetName: 'Data' });
+await chart.export('pdf', { download: true, pdfMargin: 16 });
+```
+
+`xlsx` and `pdf` are lazy-loaded and require optional dependencies (`xlsx` and
+`jspdf`) only when those formats are used.
+
 ## Documentation
 
 - [Getting Started](./docs/getting-started.md) - Installation, Vanilla JS, React integration

package/base-chart.d.ts

@@ -8,6 +8,7 @@ import type { Tooltip } from './tooltip.js';
 import type { Legend } from './legend.js';
 import type { Title } from './title.js';
 import { LayoutManager, type PlotAreaBounds } from './layout-manager.js';
+type VisualExportFormat = 'svg' | 'png' | 'jpg' | 'pdf';
 export type BaseChartConfig = {
     data: DataItem[];
     theme?: Partial<ChartTheme>;
@@ -44,7 +45,8 @@ export declare abstract class BaseChart {
     /**
      * Renders the chart to the specified target element
      */
-    render(target: string): HTMLElement | null;
+    render(target: string | HTMLElement): HTMLElement | null;
+    private resolveContainer;
     /**
      * Performs the actual rendering logic
      */
@@ -79,15 +81,22 @@ export declare abstract class BaseChart {
     protected parseValue(value: unknown): number;
     /**
      * Exports the chart in the specified format
-     * @param format - The export format ('svg' or 'json')
+     * @param format - The export format
      * @param options - Optional export options (download, filename)
-     * @returns The exported content as a string if download is false/undefined, void if download is true
+     * @returns The exported content when download is false/undefined, void if download is true
      */
-    export(format: ExportFormat, options?: ExportOptions): string | void;
+    export(format: ExportFormat, options?: ExportOptions): Promise<string | Blob | void>;
     /**
      * Downloads the exported content as a file
      */
     private downloadContent;
-    protected exportSVG(options?: ExportOptions): string;
+    private getMimeType;
+    private exportCSV;
+    private exportSize;
+    private exportXLSX;
+    private exportImage;
+    private exportPDF;
+    protected exportSVG(options?: ExportOptions, formatForHooks?: VisualExportFormat): string;
     protected exportJSON(): string;
 }
+export {};

package/base-chart.js

@@ -2,6 +2,10 @@ import { create } from 'd3';
 import { defaultTheme } from './theme.js';
 import { ChartValidator } from './validation.js';
 import { LayoutManager } from './layout-manager.js';
+import { serializeCSV } from './export-tabular.js';
+import { exportRasterBlob } from './export-image.js';
+import { exportXLSXBlob } from './export-xlsx.js';
+import { exportPDFBlob } from './export-pdf.js';
 /**
  * Base chart class that provides common functionality for all chart types
  */
@@ -134,10 +138,7 @@ export class BaseChart {
      * Renders the chart to the specified target element
      */
     render(target) {
-        const container = document.querySelector(target);
-        if (!container) {
-            throw new Error(`Container "${target}" not found`);
-        }
+        const container = this.resolveContainer(target);
         this.container = container;
         container.innerHTML = '';
         // Perform initial render
@@ -146,6 +147,19 @@ export class BaseChart {
         this.setupResizeObserver();
         return container;
     }
+    resolveContainer(target) {
+        if (target instanceof HTMLElement) {
+            return target;
+        }
+        const container = document.querySelector(target);
+        if (!container) {
+            throw new Error(`Container "${target}" not found`);
+        }
+        if (!(container instanceof HTMLElement)) {
+            throw new Error(`Container "${target}" is not an HTMLElement`);
+        }
+        return container;
+    }
     /**
      * Performs the actual rendering logic
      */
@@ -267,7 +281,6 @@ export class BaseChart {
         return svg;
     }
     // Hook for subclasses to update component layout estimates before layout calc
-    // eslint-disable-next-line @typescript-eslint/no-empty-function
     prepareLayout() { }
     /**
      * Setup ResizeObserver for automatic resize handling
@@ -321,12 +334,30 @@ export class BaseChart {
     }
     /**
      * Exports the chart in the specified format
-     * @param format - The export format ('svg' or 'json')
+     * @param format - The export format
      * @param options - Optional export options (download, filename)
-     * @returns The exported content as a string if download is false/undefined, void if download is true
+     * @returns The exported content when download is false/undefined, void if download is true
      */
-    export(format, options) {
-        const content = format === 'svg' ? this.exportSVG(options) : this.exportJSON();
+    async export(format, options) {
+        let content;
+        if (format === 'svg') {
+            content = this.exportSVG(options, 'svg');
+        }
+        else if (format === 'json') {
+            content = this.exportJSON();
+        }
+        else if (format === 'csv') {
+            content = this.exportCSV(options);
+        }
+        else if (format === 'xlsx') {
+            content = await this.exportXLSX(options);
+        }
+        else if (format === 'png' || format === 'jpg') {
+            content = await this.exportImage(format, options);
+        }
+        else {
+            content = await this.exportPDF(options);
+        }
         if (options?.download) {
             this.downloadContent(content, format, options);
             return;
@@ -337,18 +368,84 @@ export class BaseChart {
      * Downloads the exported content as a file
      */
     downloadContent(content, format, options) {
-        const mimeType = format === 'svg' ? 'image/svg+xml' : 'application/json';
-        const blob = new Blob([content], { type: mimeType });
+        const mimeType = this.getMimeType(format);
+        const blob = content instanceof Blob ? content : new Blob([content], { type: mimeType });
+        const filename = options.filename || `chart.${format}`;
         const url = URL.createObjectURL(blob);
         const link = document.createElement('a');
         link.href = url;
-        link.download = options.filename || `chart.${format}`;
+        link.download = filename;
         document.body.appendChild(link);
         link.click();
         document.body.removeChild(link);
         URL.revokeObjectURL(url);
     }
-    exportSVG(options) {
+    getMimeType(format) {
+        if (format === 'svg') {
+            return 'image/svg+xml';
+        }
+        if (format === 'json') {
+            return 'application/json';
+        }
+        if (format === 'csv') {
+            return 'text/csv;charset=utf-8';
+        }
+        if (format === 'xlsx') {
+            return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+        }
+        if (format === 'png') {
+            return 'image/png';
+        }
+        if (format === 'jpg') {
+            return 'image/jpeg';
+        }
+        return 'application/pdf';
+    }
+    exportCSV(options) {
+        return serializeCSV(this.data, options);
+    }
+    exportSize(options) {
+        return {
+            width: options?.width ?? this.width,
+            height: options?.height ?? this.height,
+        };
+    }
+    async exportXLSX(options) {
+        return exportXLSXBlob(this.data, options);
+    }
+    async exportImage(format, options) {
+        const { width, height } = this.exportSize(options);
+        const svg = this.exportSVG(options, format);
+        const backgroundColor = options?.backgroundColor ?? (format === 'jpg' ? '#ffffff' : undefined);
+        return exportRasterBlob({
+            format,
+            svg,
+            width,
+            height,
+            pixelRatio: options?.pixelRatio ?? 1,
+            backgroundColor,
+            jpegQuality: options?.jpegQuality ?? 0.92,
+        });
+    }
+    async exportPDF(options) {
+        const { width, height } = this.exportSize(options);
+        const svg = this.exportSVG(options, 'pdf');
+        const pngBlob = await exportRasterBlob({
+            format: 'png',
+            svg,
+            width,
+            height,
+            pixelRatio: options?.pixelRatio ?? 1,
+            backgroundColor: options?.backgroundColor ?? '#ffffff',
+            jpegQuality: options?.jpegQuality ?? 0.92,
+        });
+        return exportPDFBlob(pngBlob, {
+            width,
+            height,
+            margin: options?.pdfMargin ?? 0,
+        });
+    }
+    exportSVG(options, formatForHooks = 'svg') {
         if (!this.svg) {
             throw new Error('Chart must be rendered before export');
         }
@@ -360,7 +457,7 @@ export class BaseChart {
         clone.setAttribute('width', String(exportWidth));
         clone.setAttribute('height', String(exportHeight));
         const baseContext = {
-            format: 'svg',
+            format: formatForHooks,
             options,
             width: exportWidth,
             height: exportHeight,

package/donut-chart.js

@@ -157,6 +157,9 @@ export class DonutChart extends BaseChart {
         const cy = this.plotArea.top + this.plotArea.height / 2;
         const outerRadius = Math.min(this.plotArea.width, this.plotArea.height) / 2;
         const innerRadius = outerRadius * this.innerRadiusRatio;
+        if (this.tooltip) {
+            this.tooltip.initialize(this.theme);
+        }
         this.renderSegments(visibleSegments, cx, cy, innerRadius, outerRadius);
         if (this.centerContent) {
             this.centerContent.render(this.svg, cx, cy, this.theme);
@@ -169,9 +172,6 @@ export class DonutChart extends BaseChart {
             }));
             this.legend.render(this.svg, legendSeries, this.theme, this.width, pos.x, pos.y);
         }
-        if (this.tooltip) {
-            this.tooltip.initialize(this.theme);
-        }
     }
     positionTooltip(event, tooltipDiv) {
         const node = tooltipDiv.node();

package/export-image.d.ts

@@ -0,0 +1,12 @@
+type RasterFormat = 'png' | 'jpg';
+export type RasterExportOptions = {
+    format: RasterFormat;
+    svg: string;
+    width: number;
+    height: number;
+    pixelRatio: number;
+    backgroundColor?: string;
+    jpegQuality: number;
+};
+export declare function exportRasterBlob(options: RasterExportOptions): Promise<Blob>;
+export {};

package/export-image.js

@@ -0,0 +1,48 @@
+function loadImage(source) {
+    return new Promise((resolve, reject) => {
+        const image = new Image();
+        image.onload = () => resolve(image);
+        image.onerror = () => reject(new Error('Failed to load SVG for raster export'));
+        image.src = source;
+    });
+}
+function canvasToBlob(canvas, mimeType, quality) {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob((blob) => {
+            if (!blob) {
+                reject(new Error('Failed to generate image export'));
+                return;
+            }
+            resolve(blob);
+        }, mimeType, quality);
+    });
+}
+export async function exportRasterBlob(options) {
+    const { svg, width, height, format, jpegQuality } = options;
+    const pixelRatio = Math.max(1, options.pixelRatio);
+    const objectUrl = URL.createObjectURL(new Blob([svg], { type: 'image/svg+xml;charset=utf-8' }));
+    try {
+        const image = await loadImage(objectUrl);
+        const canvas = document.createElement('canvas');
+        const scaledWidth = Math.max(1, Math.round(width * pixelRatio));
+        const scaledHeight = Math.max(1, Math.round(height * pixelRatio));
+        canvas.width = scaledWidth;
+        canvas.height = scaledHeight;
+        const context = canvas.getContext('2d');
+        if (!context) {
+            throw new Error('Failed to get 2D context for image export');
+        }
+        if (options.backgroundColor) {
+            context.fillStyle = options.backgroundColor;
+            context.fillRect(0, 0, scaledWidth, scaledHeight);
+        }
+        context.drawImage(image, 0, 0, scaledWidth, scaledHeight);
+        if (format === 'png') {
+            return canvasToBlob(canvas, 'image/png');
+        }
+        return canvasToBlob(canvas, 'image/jpeg', jpegQuality);
+    }
+    finally {
+        URL.revokeObjectURL(objectUrl);
+    }
+}

package/export-pdf.d.ts

@@ -0,0 +1,8 @@
+type JsPdfLoader = () => Promise<unknown>;
+export type PDFExportOptions = {
+    width: number;
+    height: number;
+    margin: number;
+};
+export declare function exportPDFBlob(imageBlob: Blob, options: PDFExportOptions, loader?: JsPdfLoader): Promise<Blob>;
+export {};

package/export-pdf.js

@@ -0,0 +1,67 @@
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function resolveJsPdfConstructor(moduleValue) {
+    if (!isObject(moduleValue)) {
+        throw new Error('Invalid "jspdf" module export');
+    }
+    const moduleCandidate = moduleValue;
+    const defaultCandidate = moduleCandidate.default;
+    let ctor = moduleCandidate.jsPDF;
+    if (!ctor && isObject(defaultCandidate)) {
+        ctor = defaultCandidate.jsPDF;
+    }
+    if (!ctor && typeof defaultCandidate === 'function') {
+        ctor = defaultCandidate;
+    }
+    if (typeof ctor !== 'function') {
+        throw new Error('Invalid "jspdf" module export');
+    }
+    return ctor;
+}
+async function defaultJsPdfLoader() {
+    return import('jspdf');
+}
+function blobToDataUrl(blob) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(String(reader.result));
+        reader.onerror = () => reject(new Error('Failed to create PDF image data'));
+        reader.readAsDataURL(blob);
+    });
+}
+export async function exportPDFBlob(imageBlob, options, loader = defaultJsPdfLoader) {
+    let jsPdfModule;
+    try {
+        jsPdfModule = await loader();
+    }
+    catch {
+        throw new Error('PDF export requires optional dependency "jspdf". Install optional dependency "jspdf".');
+    }
+    const JsPdfCtor = resolveJsPdfConstructor(jsPdfModule);
+    const margin = Math.max(0, options.margin);
+    const pageWidth = Math.max(1, options.width + margin * 2);
+    const pageHeight = Math.max(1, options.height + margin * 2);
+    const orientation = pageWidth >= pageHeight ? 'landscape' : 'portrait';
+    const pdf = new JsPdfCtor({
+        unit: 'px',
+        format: [pageWidth, pageHeight],
+        orientation,
+        hotfixes: ['px_scaling'],
+    });
+    const actualPageWidth = pdf.internal.pageSize.getWidth();
+    const actualPageHeight = pdf.internal.pageSize.getHeight();
+    const availableWidth = actualPageWidth - margin * 2;
+    const availableHeight = actualPageHeight - margin * 2;
+    if (availableWidth <= 0 || availableHeight <= 0) {
+        throw new Error('Invalid PDF margin: no drawable area remains');
+    }
+    const imageDataUrl = await blobToDataUrl(imageBlob);
+    const scale = Math.min(availableWidth / options.width, availableHeight / options.height);
+    const drawWidth = options.width * scale;
+    const drawHeight = options.height * scale;
+    const x = (actualPageWidth - drawWidth) / 2;
+    const y = (actualPageHeight - drawHeight) / 2;
+    pdf.addImage(imageDataUrl, 'PNG', x, y, drawWidth, drawHeight);
+    return pdf.output('blob');
+}

package/export-tabular.d.ts

@@ -0,0 +1,9 @@
+import type { DataItem, ExportOptions } from './types.js';
+type TabularData = {
+    columns: string[];
+    rows: string[][];
+};
+export declare function resolveTableColumns(data: DataItem[], requestedColumns?: string[]): string[];
+export declare function toTabularData(data: DataItem[], requestedColumns?: string[]): TabularData;
+export declare function serializeCSV(data: DataItem[], options?: ExportOptions): string;
+export {};

package/export-tabular.js

@@ -0,0 +1,61 @@
+function normalizeTableValue(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === 'object') {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    return String(value);
+}
+function escapeCSVValue(value, delimiter) {
+    const escaped = value.replace(/"/g, '""');
+    const needsQuotes = escaped.includes('"') ||
+        escaped.includes(delimiter) ||
+        escaped.includes('\n') ||
+        escaped.includes('\r');
+    if (!needsQuotes) {
+        return escaped;
+    }
+    return `"${escaped}"`;
+}
+export function resolveTableColumns(data, requestedColumns) {
+    if (requestedColumns && requestedColumns.length > 0) {
+        return requestedColumns;
+    }
+    const columns = [];
+    const seen = new Set();
+    data.forEach((item) => {
+        Object.keys(item).forEach((key) => {
+            if (!seen.has(key)) {
+                seen.add(key);
+                columns.push(key);
+            }
+        });
+    });
+    return columns;
+}
+export function toTabularData(data, requestedColumns) {
+    const columns = resolveTableColumns(data, requestedColumns);
+    const rows = data.map((item) => columns.map((column) => normalizeTableValue(item[column])));
+    return {
+        columns,
+        rows,
+    };
+}
+export function serializeCSV(data, options) {
+    const delimiter = options?.delimiter ?? ',';
+    const { columns, rows } = toTabularData(data, options?.columns);
+    const serializedRows = [
+        columns.map((column) => escapeCSVValue(column, delimiter)).join(delimiter),
+        ...rows.map((row) => row.map((value) => escapeCSVValue(value, delimiter)).join(delimiter)),
+    ];
+    return serializedRows.join('\n');
+}

package/export-xlsx.d.ts

@@ -0,0 +1,4 @@
+import type { DataItem, ExportOptions } from './types.js';
+type XlsxLoader = () => Promise<unknown>;
+export declare function exportXLSXBlob(data: DataItem[], options?: ExportOptions, loader?: XlsxLoader): Promise<Blob>;
+export {};

package/export-xlsx.js

@@ -0,0 +1,44 @@
+import { toTabularData } from './export-tabular.js';
+const XLSX_MIME_TYPE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function resolveXlsxApi(moduleValue) {
+    if (!isObject(moduleValue)) {
+        throw new Error('Invalid "xlsx" module export');
+    }
+    const moduleCandidate = moduleValue;
+    const xlsxCandidate = moduleCandidate.default && isObject(moduleCandidate.default)
+        ? moduleCandidate.default
+        : moduleCandidate;
+    if (!xlsxCandidate.utils || !xlsxCandidate.write) {
+        throw new Error('Invalid "xlsx" module export');
+    }
+    return {
+        utils: xlsxCandidate.utils,
+        write: xlsxCandidate.write,
+    };
+}
+async function defaultXlsxLoader() {
+    return import('xlsx');
+}
+export async function exportXLSXBlob(data, options, loader = defaultXlsxLoader) {
+    let xlsxModule;
+    try {
+        xlsxModule = await loader();
+    }
+    catch {
+        throw new Error('XLSX export requires optional dependency "xlsx". Install optional dependency "xlsx".');
+    }
+    const xlsx = resolveXlsxApi(xlsxModule);
+    const { columns, rows } = toTabularData(data, options?.columns);
+    const worksheet = xlsx.utils.aoa_to_sheet([columns, ...rows]);
+    const workbook = xlsx.utils.book_new();
+    const sheetName = options?.sheetName?.trim() || 'Sheet1';
+    xlsx.utils.book_append_sheet(workbook, worksheet, sheetName);
+    const buffer = xlsx.write(workbook, {
+        type: 'array',
+        bookType: 'xlsx',
+    });
+    return new Blob([buffer], { type: XLSX_MIME_TYPE });
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "0.4.1",
+    "version": "0.4.3",
     "name": "@internetstiftelsen/charts",
     "type": "module",
     "sideEffects": false,
@@ -42,16 +42,20 @@
         "tailwind-merge": "^3.4.0",
         "tailwindcss": "^4.1.18"
     },
+    "optionalDependencies": {
+        "jspdf": "^4.1.0",
+        "xlsx": "^0.18.5"
+    },
     "devDependencies": {
         "@eslint/js": "^9.39.2",
         "@tailwindcss/vite": "^4.1.18",
         "@testing-library/dom": "^10.4.1",
         "@testing-library/jest-dom": "^6.9.1",
         "@testing-library/react": "^16.3.2",
-        "@types/node": "^24.10.9",
-        "@types/react": "^19.2.10",
+        "@types/node": "^24.10.13",
+        "@types/react": "^19.2.14",
         "@types/react-dom": "^19.2.3",
-        "@vitejs/plugin-react-swc": "^4.2.2",
+        "@vitejs/plugin-react-swc": "^4.2.3",
         "eslint": "^9.39.2",
         "eslint-plugin-react-hooks": "^7.0.1",
         "eslint-plugin-react-refresh": "^0.4.26",
@@ -61,7 +65,7 @@
         "tsc-alias": "^1.8.16",
         "tw-animate-css": "^1.4.0",
         "typescript": "~5.9.3",
-        "typescript-eslint": "^8.54.0",
+        "typescript-eslint": "^8.55.0",
         "vite": "^7.3.1",
         "vitest": "^4.0.18"
     }

package/types.d.ts

@@ -1,11 +1,18 @@
 export type DataValue = string | number | boolean | Date | null | undefined;
 export type DataItem = Record<string, any>;
-export type ExportFormat = 'svg' | 'json';
+export type ExportFormat = 'svg' | 'json' | 'csv' | 'xlsx' | 'png' | 'jpg' | 'pdf';
 export type ExportOptions = {
     download?: boolean;
     filename?: string;
     width?: number;
     height?: number;
+    columns?: string[];
+    delimiter?: string;
+    jpegQuality?: number;
+    pixelRatio?: number;
+    backgroundColor?: string;
+    sheetName?: string;
+    pdfMargin?: number;
 };
 export type ExportRenderContext = {
     format: ExportFormat;