@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/esm/modules/pdf/excel-bridge.js

@@ -14,10 +14,18 @@
  * const pdf = await excelToPdf(workbook);
  * ```
  */
+// Chart runtime is accessed through the chart-host-registry slot so
+// `@pkg/pdf` can do excel-to-PDF conversion without statically pulling
+// ~1.2 MB of chart rendering code into every consumer's bundle.
+// Consumers that convert workbooks with charts must call
+// `installChartSupport()` from `@cj-tech-master/excelts/chart` before
+// invoking `excelToPdf()`.
+import { getChartSupport } from "../excel/chart-host-registry.js";
 import { ValueType } from "../excel/enums.js";
 import { formatCellValue } from "../excel/utils/cell-format.js";
 import { tryInvokeFormulaEngine } from "../formula/host-registry.js";
 import { base64ToUint8Array } from "../../utils/utils.base.js";
+import { PdfDocumentBuilder } from "./builder/document-builder.js";
 import { exportPdf } from "./render/pdf-exporter.js";
 import { PdfCellType } from "./types.js";
 // =============================================================================
@@ -43,24 +51,132 @@ export async function excelToPdf(workbook, options) {
     // who don't import it fall back to whatever cached results the XLSX
     // shipped with (safe for workbooks last saved by Excel itself).
     tryInvokeFormulaEngine(workbook);
-    const pdfWorkbook = excelWorkbookToPdf(workbook);
+    const pdfWorkbook = await excelWorkbookToPdf(workbook);
     return exportPdf(pdfWorkbook, options);
 }
+/**
+ * Render a single {@link Chart} to a standalone one-page PDF.
+ *
+ * The output is a **zero-dependency deterministic preview**, not an
+ * Excel-pixel-perfect rendering. Use this for server-side reports,
+ * thumbnails, and CI artefacts where the goal is a recognisable chart
+ * without a headless Office dependency. When pixel-identical output
+ * matters (publication-grade reports, Excel/LibreOffice-compatible
+ * formatting), round-trip the `.xlsx` through
+ * `soffice --convert-to pdf` — the byte-preserving round-trip in this
+ * library makes that a safe handoff. See `src/modules/excel/README.md`
+ * → "Rendering scope" for the complete boundary list.
+ *
+ * Classic charts take the **vector** path: the chart is drawn directly
+ * onto the page via `drawChartPdf`, so text stays selectable and shapes
+ * remain resolution-independent. ChartEx charts whose layout IDs are in
+ * `VECTOR_PDF_CHART_EX_LAYOUT_IDS` also take the vector path via
+ * `drawChartExPdf`; unsupported layouts (if any) and charts where
+ * `forceRaster: true` is set fall through to the SVG → PNG → image-XObject
+ * raster pipeline.
+ *
+ * Lives in `excel-bridge.ts` because invoking the PDF builder from the
+ * chart module would cross the Layer 4 → Layer 5 import boundary
+ * documented in `AGENTS.md`. Consumers import it from
+ * `@cj-tech-master/excelts/pdf` alongside `excelToPdf`.
+ */
+export async function chartToPdf(chart, options = {}) {
+    const width = options.width ?? 520;
+    const height = options.height ?? 360;
+    const margin = options.margin ?? 36;
+    const pageWidth = options.pageWidth ?? Math.max(width + margin * 2, 400);
+    const pageHeight = options.pageHeight ?? Math.max(height + margin * 2, 300);
+    const doc = new PdfDocumentBuilder();
+    if (options.title || options.author) {
+        doc.setMetadata({
+            title: options.title,
+            author: options.author
+        });
+    }
+    const page = doc.addPage({ width: pageWidth, height: pageHeight });
+    const isChartEx = chart.chartExModel !== undefined;
+    // ChartEx charts whose every series has a layoutId in
+    // VECTOR_PDF_CHART_EX_LAYOUT_IDS take the vector route alongside
+    // classic charts. As of the regionMap port this covers every ChartEx
+    // layout the builder currently emits. Anything else — or any chart
+    // the caller explicitly asks to rasterise via `forceRaster` — falls
+    // through to the SVG → PNG → image-XObject pipeline.
+    const chartExModel = chart.chartExModel;
+    const chartExVectorable = isChartEx &&
+        chartExModel !== undefined &&
+        getChartSupport().canRenderChartExAsVectorPdf(chartExModel);
+    const useRaster = options.forceRaster === true || (isChartEx && !chartExVectorable);
+    if (!useRaster) {
+        if (isChartEx && chartExModel !== undefined) {
+            getChartSupport().drawChartExPdf(page, chartExModel, {
+                x: margin,
+                y: pageHeight - margin - height,
+                width,
+                height
+            }, { title: options.title, regionMap: options.regionMap });
+            return doc.build();
+        }
+        // Vector path for classic charts.
+        const model = chart.chartModel;
+        if (!model) {
+            throw new Error("chartToPdf: Chart has neither a classic model nor a ChartEx model to render");
+        }
+        getChartSupport().drawChartPdf(page, model, {
+            x: margin,
+            y: pageHeight - margin - height,
+            width,
+            height
+        });
+        return doc.build();
+    }
+    // Raster path: produce a PNG, then embed it on the page. Uses scale
+    // 2× by default so the PDF viewer shows crisp text even when zoomed
+    // into a 150 % magnification. Callers who need larger prints can
+    // bump `rasterScale`; anything above 4 rapidly grows the PDF size.
+    const scale = options.rasterScale ?? 2;
+    const pngBytes = isChartEx
+        ? await getChartSupport().renderChartExPng(chart.chartExModel, { width, height, scale })
+        : await getChartSupport().renderChartPng(chart.chartModel, { width, height, scale });
+    page.drawImage({
+        data: pngBytes,
+        format: "png",
+        x: margin,
+        y: pageHeight - margin - height,
+        width,
+        height
+    });
+    return doc.build();
+}
 /**
  * Convert an Excel Workbook to the internal PdfWorkbook data structure.
+ *
+ * Async because two conversion paths hand off work that may be off-thread:
+ *  - Non-whitelisted ChartEx layouts are rasterised to PNG at collection
+ *    time via `renderChartExPng` (so the exporter never blocks on chart
+ *    rendering).
+ *  - Chartsheets follow the same per-chart rasterisation rule.
+ *
+ * Worksheets and chartsheets are merged into a single `sheets` array in
+ * tab order (`orderNo`), matching what Excel / LibreOffice would print.
+ * Chartsheets without an orderNo fall to the end, mirroring how Excel
+ * treats sheets with missing tab positions.
  */
-function excelWorkbookToPdf(workbook) {
+async function excelWorkbookToPdf(workbook) {
+    const worksheetResults = await Promise.all(workbook.worksheets.map(ws => convertSheet(ws, workbook)));
+    const chartsheetResults = await Promise.all(workbook.chartsheets.map(cs => convertChartsheet(cs)));
+    const combined = [...worksheetResults, ...chartsheetResults];
+    combined.sort((a, b) => (a.orderNo ?? Number.POSITIVE_INFINITY) - (b.orderNo ?? Number.POSITIVE_INFINITY));
     return {
         title: workbook.title || undefined,
         creator: workbook.creator || undefined,
         subject: workbook.subject || undefined,
-        sheets: workbook.worksheets.map(ws => convertSheet(ws, workbook))
+        sheets: combined
     };
 }
 // =============================================================================
 // Sheet Conversion
 // =============================================================================
-function convertSheet(ws, workbook) {
+async function convertSheet(ws, workbook) {
     const dimensions = ws.dimensions;
     const hasData = dimensions && dimensions.model.top > 0 && dimensions.model.left > 0;
     const bounds = hasData
@@ -138,12 +254,32 @@ function convertSheet(ws, workbook) {
     // Convert row/col breaks
     const rowBreaks = ws.rowBreaks?.map((b) => b.id);
     const colBreaks = ws.colBreaks?.map((b) => b.id);
-    // Convert images
+    // Convert images and charts. Both are floating objects anchored to
+    // cells, and both need to participate in bounds expansion so the
+    // layout engine allocates pages that cover their anchor rows/cols.
     const images = collectImages(ws, workbook);
-    // Extend bounds to cover image anchors (so layout engine includes them)
+    const charts = await collectCharts(ws);
+    const sparklineCharts = collectSparklineCharts(ws);
+    // Merge sparkline micro-charts with regular charts
+    const allCharts = charts
+        ? sparklineCharts
+            ? [...charts, ...sparklineCharts]
+            : charts
+        : sparklineCharts || undefined;
+    const anchoredRanges = [];
     if (images) {
         for (const img of images) {
-            const tl = img.range.tl;
+            anchoredRanges.push(img.range);
+        }
+    }
+    if (allCharts) {
+        for (const ch of allCharts) {
+            anchoredRanges.push(ch.range);
+        }
+    }
+    if (anchoredRanges.length > 0) {
+        for (const range of anchoredRanges) {
+            const tl = range.tl;
             const tlCol = (tl.nativeCol ?? tl.col ?? 0) + 1; // 0-indexed → 1-indexed
             const tlRow = (tl.nativeRow ?? tl.row ?? 0) + 1;
             if (bounds.top === 0 && bounds.left === 0) {
@@ -157,8 +293,8 @@ function convertSheet(ws, workbook) {
                 bounds.bottom = tlRow;
             }
             // Also extend to bottom-right anchor if present
-            if (img.range.br) {
-                const br = img.range.br;
+            if (range.br) {
+                const br = range.br;
                 const brCol = (br.nativeCol ?? br.col ?? 0) + 1;
                 const brRow = (br.nativeRow ?? br.row ?? 0) + 1;
                 if (brCol > bounds.right) {
@@ -186,8 +322,10 @@ function convertSheet(ws, workbook) {
         }
     }
     return {
+        kind: "worksheet",
         name: ws.name,
         state: ws.state ?? "visible",
+        orderNo: ws.orderNo,
         bounds,
         columns,
         rows,
@@ -195,7 +333,8 @@ function convertSheet(ws, workbook) {
         pageSetup,
         rowBreaks,
         colBreaks,
-        images
+        images,
+        charts: allCharts
     };
 }
 // =============================================================================
@@ -436,10 +575,542 @@ function collectImages(ws, workbook) {
                     }
                     : undefined,
                 ext: wsImage.range.ext
-                    ? { width: wsImage.range.ext.width, height: wsImage.range.ext.height }
-                    : undefined
+                    ? {
+                        width: wsImage.range.ext.width,
+                        height: wsImage.range.ext.height
+                    }
+                    : undefined,
+                // Images historically store ext as pixels — the layout engine
+                // converts px→pt at assignment time (px × 0.75 = pt).
+                extUnit: wsImage.range.ext ? "px" : undefined
             }
         });
     }
     return images.length > 0 ? images : undefined;
 }
+// =============================================================================
+// Chart Collection
+// =============================================================================
+/**
+ * Gather every embedded chart on a worksheet and wrap it in a
+ * {@link PdfSheetChart} the layout engine can place.
+ *
+ * - **Classic charts** and **whitelisted ChartEx layouts** get a
+ *   `drawVector` closure pinned over the chart model. The closure is
+ *   invoked later by the PDF exporter against a drawing surface adapted
+ *   over the page's content stream (see `render/chart-surface.ts`), so
+ *   the chart ends up as real PDF geometry — selectable text, crisp
+ *   shapes at any zoom.
+ * - **ChartEx layouts outside the whitelist** are rasterised up-front
+ *   via `renderChartExPng` and attached as a raster payload. The
+ *   exporter then treats the PNG as an image XObject. The raster size
+ *   is derived from the anchor extent (with a sensible fallback), and
+ *   the PDF viewer stretches the bitmap to the final rect.
+ *
+ * Pivot charts inherit the classic path — they are regular `Chart`
+ * objects with a `pivotSource` tag, and their model renders like any
+ * other classic chart.
+ */
+async function collectCharts(ws) {
+    const wsCharts = ws.getCharts?.();
+    if (!wsCharts || !Array.isArray(wsCharts) || wsCharts.length === 0) {
+        return undefined;
+    }
+    const charts = [];
+    for (const chart of wsCharts) {
+        const range = chartAnchorRange(chart);
+        if (!range) {
+            continue;
+        }
+        const classicModel = chart.chartModel;
+        const chartExModel = chart.chartExModel;
+        if (classicModel) {
+            // Classic chart → vector path.
+            const drawVector = (surface, rect) => {
+                getChartSupport().drawChartPdf(surface, classicModel, {
+                    x: rect.x,
+                    y: rect.y,
+                    width: rect.width,
+                    height: rect.height
+                });
+            };
+            charts.push({ range, drawVector });
+            continue;
+        }
+        if (chartExModel) {
+            // Hierarchical ChartEx (treemap/sunburst) marks its dims with
+            // `_skipCache` to prevent the XLSX writer from emitting flat
+            // cache levels (which confuses Excel). For PDF rendering we need
+            // the data in-memory, so temporarily lift the flag, fill caches
+            // from the worksheet, then restore it.
+            ensureChartExCachesFilled(chartExModel, ws);
+            if (getChartSupport().canRenderChartExAsVectorPdf(chartExModel)) {
+                // Whitelisted ChartEx layout → vector path.
+                const drawVector = (surface, rect) => {
+                    getChartSupport().drawChartExPdf(surface, chartExModel, { x: rect.x, y: rect.y, width: rect.width, height: rect.height });
+                };
+                charts.push({ range, drawVector });
+            }
+            else {
+                // Non-whitelisted ChartEx layout → raster path.
+                const { widthPx, heightPx } = estimateChartPixelSize(range);
+                const png = await getChartSupport().renderChartExPng(chartExModel, {
+                    width: widthPx,
+                    height: heightPx,
+                    scale: 2
+                });
+                charts.push({
+                    range,
+                    raster: { data: png, format: "png" }
+                });
+            }
+            continue;
+        }
+        // Chart has neither model — likely a placeholder or unparsed
+        // `rawXml` shape. Rasterise nothing, skip silently; the cells
+        // underneath remain visible.
+    }
+    return charts.length > 0 ? charts : undefined;
+}
+/**
+ * Convert worksheet sparkline groups into micro-chart entries that flow
+ * through the same chart rendering pipeline. Each sparkline becomes a
+ * `PdfSheetChart` anchored to its `cellRef` cell (one cell wide, one
+ * row tall) with a `drawVector` callback that paints the sparkline's
+ * geometry (line polyline or column bars) directly into the PDF page.
+ */
+function collectSparklineCharts(ws) {
+    const groups = ws.getSparklineGroups?.();
+    if (!groups || groups.length === 0) {
+        return undefined;
+    }
+    const charts = [];
+    for (const group of groups) {
+        for (const sparkline of group.sparklines) {
+            const { dataRef, cellRef } = sparkline;
+            if (!cellRef) {
+                continue;
+            }
+            // Parse cellRef (e.g. "N3") to get row/col
+            const cellMatch = cellRef.match(/^([A-Z]+)(\d+)$/i);
+            if (!cellMatch) {
+                continue;
+            }
+            const col = colLetterToNumber(cellMatch[1]);
+            const row = parseInt(cellMatch[2], 10);
+            // Resolve data values from the worksheet
+            const values = resolveSparklineData(ws, dataRef);
+            if (values.length === 0) {
+                continue;
+            }
+            // Build anchor: the sparkline occupies exactly one cell
+            const range = {
+                tl: { col: col - 1, row: row - 1, nativeCol: col - 1, nativeRow: row - 1 },
+                br: { col, row, nativeCol: col, nativeRow: row }
+            };
+            const drawVector = (surface, rect) => {
+                drawSparklinePdf(surface, group, values, rect);
+            };
+            charts.push({ range, drawVector });
+        }
+    }
+    return charts.length > 0 ? charts : undefined;
+}
+/** Convert column letter(s) to 1-based number. */
+function colLetterToNumber(letters) {
+    let n = 0;
+    for (let i = 0; i < letters.length; i++) {
+        n = n * 26 + (letters.charCodeAt(i) & 0x1f);
+    }
+    return n;
+}
+/** Resolve sparkline data reference to numeric values. */
+function resolveSparklineData(ws, dataRef) {
+    if (!dataRef) {
+        return [];
+    }
+    // dataRef is like "Sheet1!B3:M3" or "'Regional KPIs'!B3:M3"
+    // Strip sheet prefix — sparklines always reference the same workbook
+    const bangIdx = dataRef.lastIndexOf("!");
+    const rangeStr = bangIdx >= 0 ? dataRef.slice(bangIdx + 1) : dataRef;
+    // Determine the source worksheet
+    let sourceWs = ws;
+    if (bangIdx >= 0) {
+        let sheetName = dataRef.slice(0, bangIdx);
+        // Remove surrounding quotes
+        if (sheetName.startsWith("'") && sheetName.endsWith("'")) {
+            sheetName = sheetName.slice(1, -1).replace(/''/g, "'");
+        }
+        const found = ws.workbook?.getWorksheet?.(sheetName);
+        if (found) {
+            sourceWs = found;
+        }
+    }
+    // Parse range (e.g. "$B$3:$M$3" or "A1:K1")
+    const clean = rangeStr.replace(/\$/g, "");
+    const parts = clean.split(":");
+    if (parts.length !== 2) {
+        return [];
+    }
+    const startMatch = parts[0].match(/^([A-Z]+)(\d+)$/i);
+    const endMatch = parts[1].match(/^([A-Z]+)(\d+)$/i);
+    if (!startMatch || !endMatch) {
+        return [];
+    }
+    const startCol = colLetterToNumber(startMatch[1]);
+    const startRow = parseInt(startMatch[2], 10);
+    const endCol = colLetterToNumber(endMatch[1]);
+    const endRow = parseInt(endMatch[2], 10);
+    const values = [];
+    if (startRow === endRow) {
+        // Horizontal range
+        for (let c = startCol; c <= endCol; c++) {
+            const cell = sourceWs.getCell(startRow, c);
+            const v = typeof cell.value === "number" ? cell.value : (cell.result ?? NaN);
+            values.push(typeof v === "number" ? v : NaN);
+        }
+    }
+    else {
+        // Vertical range
+        for (let r = startRow; r <= endRow; r++) {
+            const cell = sourceWs.getCell(r, startCol);
+            const v = typeof cell.value === "number" ? cell.value : (cell.result ?? NaN);
+            values.push(typeof v === "number" ? v : NaN);
+        }
+    }
+    return values;
+}
+/**
+ * Draw a single sparkline into a PDF rect. Mirrors the logic of
+ * `renderSparklineSvg` but emits PDF drawing primitives via the
+ * chart surface.
+ */
+function drawSparklinePdf(surface, group, values, rect) {
+    const { x, y, width, height } = rect;
+    if (width <= 0 || height <= 0 || values.length === 0) {
+        return;
+    }
+    const padding = 2;
+    const innerX = x + padding;
+    const innerY = y + padding;
+    const innerW = width - padding * 2;
+    const innerH = height - padding * 2;
+    if (innerW <= 0 || innerH <= 0) {
+        return;
+    }
+    // Compute axis range
+    const finiteValues = values.filter(v => Number.isFinite(v));
+    if (finiteValues.length === 0) {
+        return;
+    }
+    let min = Math.min(...finiteValues);
+    let max = Math.max(...finiteValues);
+    if (group.minAxisType === "custom" && group.manualMin !== undefined) {
+        min = group.manualMin;
+    }
+    if (group.maxAxisType === "custom" && group.manualMax !== undefined) {
+        max = group.manualMax;
+    }
+    if (min === max) {
+        min -= 1;
+        max += 1;
+    }
+    const span = max - min;
+    const rtl = group.rightToLeft === true;
+    const n = values.length;
+    const xAt = (i) => {
+        const t = n <= 1 ? 0.5 : i / (n - 1);
+        const shifted = rtl ? 1 - t : t;
+        return innerX + shifted * innerW;
+    };
+    // PDF y-up: higher values → higher y
+    const yAt = (v) => {
+        if (!Number.isFinite(v)) {
+            return innerY;
+        }
+        const t = (v - min) / span;
+        return innerY + t * innerH;
+    };
+    const lineColor = resolveSpkColor(group.colorSeries) ?? { r: 0.22, g: 0.38, b: 0.57 };
+    const negColor = resolveSpkColor(group.colorNegative) ?? { r: 0.82, g: 0, b: 0 };
+    if (group.type === "column" || group.type === "stacked") {
+        const barW = Math.max(1, (innerW / Math.max(n, 1)) * 0.8);
+        for (let i = 0; i < n; i++) {
+            const v = values[i];
+            if (!Number.isFinite(v) || v === 0) {
+                continue;
+            }
+            const cx = xAt(i);
+            const bx = cx - barW / 2;
+            const color = v < 0 && group.negative === true ? negColor : lineColor;
+            let barY;
+            let barH;
+            if (group.type === "stacked") {
+                const half = innerH / 2;
+                if (v >= 0) {
+                    barY = innerY + half;
+                    barH = half;
+                }
+                else {
+                    barY = innerY;
+                    barH = half;
+                }
+            }
+            else {
+                const base = min <= 0 && max >= 0 ? yAt(0) : innerY;
+                const top = yAt(v);
+                barY = Math.min(base, top);
+                barH = Math.abs(top - base);
+            }
+            surface.drawRect({ x: bx, y: barY, width: barW, height: Math.max(barH, 0.5), fill: color });
+        }
+    }
+    else {
+        // Line sparkline
+        const points = [];
+        for (let i = 0; i < n; i++) {
+            if (Number.isFinite(values[i])) {
+                points.push({ px: xAt(i), py: yAt(values[i]) });
+            }
+        }
+        if (points.length >= 2) {
+            for (let i = 1; i < points.length; i++) {
+                surface.drawLine({
+                    x1: points[i - 1].px,
+                    y1: points[i - 1].py,
+                    x2: points[i].px,
+                    y2: points[i].py,
+                    color: lineColor,
+                    lineWidth: group.lineWeight ? group.lineWeight * 0.75 : 0.75
+                });
+            }
+        }
+        // Markers
+        if (group.markers && surface.drawCircle) {
+            const mkColor = resolveSpkColor(group.colorMarkers) ?? lineColor;
+            for (const p of points) {
+                surface.drawCircle({ cx: p.px, cy: p.py, r: 1.2, fill: mkColor });
+            }
+        }
+    }
+}
+/** Resolve a SparklineColor to a PdfColor-like {r,g,b}. */
+function resolveSpkColor(c) {
+    if (!c) {
+        return undefined;
+    }
+    if (c.rgb) {
+        const hex = c.rgb.replace(/^#/, "").replace(/^FF/i, "");
+        const r = parseInt(hex.slice(0, 2), 16) / 255;
+        const g = parseInt(hex.slice(2, 4), 16) / 255;
+        const b = parseInt(hex.slice(4, 6), 16) / 255;
+        if (Number.isFinite(r) && Number.isFinite(g) && Number.isFinite(b)) {
+            return { r, g, b };
+        }
+    }
+    return undefined;
+}
+/**
+ * Translate a `Chart.range` into the PDF layer's anchor shape. Returns
+ * `undefined` for charts that ExcelTS could not anchor to any cell
+ * (extremely rare — usually indicates a corrupt drawing relationship).
+ */
+function chartAnchorRange(chart) {
+    const r = chart.range;
+    if (!r?.tl) {
+        return undefined;
+    }
+    const tl = r.tl;
+    const br = r.br;
+    return {
+        tl: {
+            col: tl.col ?? 0,
+            row: tl.row ?? 0,
+            nativeCol: tl.nativeCol,
+            nativeRow: tl.nativeRow,
+            nativeColOff: tl.nativeColOff,
+            nativeRowOff: tl.nativeRowOff
+        },
+        br: br
+            ? {
+                col: br.col ?? 0,
+                row: br.row ?? 0,
+                nativeCol: br.nativeCol,
+                nativeRow: br.nativeRow,
+                nativeColOff: br.nativeColOff,
+                nativeRowOff: br.nativeRowOff
+            }
+            : undefined,
+        // Chart anchors store ext as EMU (`cx`, `cy`). Pass the values
+        // through unchanged; the layout engine converts EMU→pt for charts
+        // (×1/9525) and px→pt for images (×0.75) based on `extUnit`.
+        ext: r.ext ? { width: r.ext.cx, height: r.ext.cy } : undefined,
+        extUnit: r.ext ? "emu" : undefined
+    };
+}
+/**
+ * Ensure a ChartEx model's data caches are populated for rendering.
+ *
+ * Hierarchical charts (treemap/sunburst) set `_skipCache` on their
+ * string/numeric dimensions so the XLSX writer doesn't emit flat cache
+ * levels (Excel rejects them). For PDF/image rendering the data must be
+ * in-memory. This helper temporarily lifts the flag, calls
+ * `fillChartExCaches`, then restores it so subsequent XLSX writes are
+ * unaffected.
+ */
+function ensureChartExCachesFilled(model, ws) {
+    const data = model.chartSpace?.chartData?.data;
+    if (!data) {
+        return;
+    }
+    // Check if any dimension is missing cache data
+    const needsFill = data.some(entry => {
+        const strNeedsData = entry.strDim && (!entry.strDim.levels || entry.strDim.levels.length === 0);
+        const numNeedsData = entry.numDim && (!entry.numDim.levels || entry.numDim.levels.length === 0);
+        return strNeedsData || numNeedsData;
+    });
+    if (!needsFill) {
+        return;
+    }
+    // Temporarily lift _skipCache flags
+    const skipped = [];
+    for (const entry of data) {
+        const str = entry.strDim;
+        if (str?.["_skipCache"]) {
+            skipped.push(str);
+            delete str["_skipCache"];
+        }
+        const num = entry.numDim;
+        if (num?.["_skipCache"]) {
+            skipped.push(num);
+            delete num["_skipCache"];
+        }
+    }
+    try {
+        getChartSupport().fillChartExCaches(model, ws.workbook, ws);
+    }
+    catch {
+        // Best-effort — rendering will proceed with whatever data is available.
+    }
+    // Restore _skipCache
+    for (const dim of skipped) {
+        dim["_skipCache"] = true;
+    }
+}
+/**
+ * Pick a PNG rasterisation size for a non-vectorable ChartEx layout.
+ *
+ * Strategy: use the anchor extent (EMU → pt → px at 96 dpi) when
+ * available; otherwise fall back to a reasonable default that survives
+ * half-page stretching without obvious artefacts. The exporter's
+ * `rasterScale` is applied separately in `collectCharts`.
+ */
+function estimateChartPixelSize(range) {
+    if (range.ext && range.extUnit === "emu") {
+        const widthPt = range.ext.width / 9525;
+        const heightPt = range.ext.height / 9525;
+        // 1 pt = 1/72 in ≈ 96/72 px at 96 dpi
+        return {
+            widthPx: Math.max(120, Math.round(widthPt * (96 / 72))),
+            heightPx: Math.max(80, Math.round(heightPt * (96 / 72)))
+        };
+    }
+    return { widthPx: 640, heightPx: 420 };
+}
+// =============================================================================
+// Chartsheet Conversion
+// =============================================================================
+/**
+ * Pixel dimensions used when rasterising a non-whitelisted ChartEx on a
+ * chartsheet. Derived from Excel's own chartsheet canvas defaults
+ * (A4 landscape minus default margins — see `CHARTSHEET_EMU_CX / CY`
+ * in `xlsx.browser.ts`). 2× is applied by `renderChartExPng` via the
+ * `scale` option so the PNG looks crisp at 150% zoom.
+ */
+const CHARTSHEET_RASTER_PX = { width: 1280, height: 720 };
+/**
+ * Convert a {@link Chartsheet} into a {@link PdfChartsheetData}.
+ *
+ * A chartsheet is a "single chart fills the whole page" sheet type. Unlike
+ * a cell-grid worksheet there is no row/column layout to reason about —
+ * the chart just takes whatever content area the page margins leave.
+ *
+ * - **Classic chart** → vector `drawChartPdf` path (selectable text,
+ *   crisp at any zoom).
+ * - **ChartEx whitelisted layout** → vector `drawChartExPdf` path.
+ * - **ChartEx outside the whitelist** → rasterised to PNG up-front via
+ *   `renderChartExPng`; the PDF viewer stretches the bitmap to the final
+ *   page rect.
+ * - **No chart attached** → the chartsheet still produces a blank page
+ *   (matches what Excel prints for a chartsheet whose chart was deleted
+ *   but the sheet kept).
+ */
+async function convertChartsheet(cs) {
+    const classicModel = cs.chartModel;
+    const chartExModel = cs.chartExModel;
+    let chart = {};
+    if (classicModel) {
+        const model = classicModel;
+        chart = {
+            drawVector: (surface, rect) => {
+                getChartSupport().drawChartPdf(surface, model, {
+                    x: rect.x,
+                    y: rect.y,
+                    width: rect.width,
+                    height: rect.height
+                });
+            }
+        };
+    }
+    else if (chartExModel) {
+        if (getChartSupport().canRenderChartExAsVectorPdf(chartExModel)) {
+            const model = chartExModel;
+            chart = {
+                drawVector: (surface, rect) => {
+                    getChartSupport().drawChartExPdf(surface, model, {
+                        x: rect.x,
+                        y: rect.y,
+                        width: rect.width,
+                        height: rect.height
+                    });
+                }
+            };
+        }
+        else {
+            const png = await getChartSupport().renderChartExPng(chartExModel, {
+                width: CHARTSHEET_RASTER_PX.width,
+                height: CHARTSHEET_RASTER_PX.height,
+                scale: 2
+            });
+            chart = { raster: { data: png, format: "png" } };
+        }
+    }
+    // Chartsheet orientation: explicit pageSetup wins. Excel's chartsheet
+    // convention is landscape when unset (the CHARTSHEET_EMU_CX/CY pair in
+    // xlsx.browser.ts is wider than tall), so we inherit that default.
+    const explicitOrientation = cs.pageSetup?.orientation;
+    const orientation = explicitOrientation === "portrait" || explicitOrientation === "landscape"
+        ? explicitOrientation
+        : "landscape";
+    // Capture the native pageSetup for callers / exporter heuristics.
+    // Chartsheet's `CT_CsPageSetup` is a subset of worksheet's `CT_PageSetup`;
+    // the fields we surface here are the ones the PDF renderer knows how
+    // to interpret. Unknown fields are silently dropped.
+    const ps = cs.pageSetup;
+    const pageSetup = ps
+        ? {
+            orientation: ps.orientation,
+            paperSize: ps.paperSize,
+            showGridLines: false
+        }
+        : undefined;
+    return {
+        kind: "chartsheet",
+        name: cs.name,
+        state: cs.state,
+        orderNo: cs.model.orderNo,
+        orientation,
+        chart,
+        pageSetup
+    };
+}