documonster 0.7.0 → 0.8.0

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

@@ -66,7 +66,7 @@ async function excelToPdf(workbook, options) {
     // shipped with. This keeps the ~200 KB engine out of bundles that only
     // export already-computed workbooks — no host-registry needed.
     options?.recalculate?.(workbook);
-    const pdfWorkbook = await excelWorkbookToPdf(workbook);
+    const pdfWorkbook = await excelWorkbookToPdf(workbook, options);
     return (0, pdf_exporter_1.exportPdf)(pdfWorkbook, options);
 }
 /**
@@ -178,9 +178,9 @@ async function chartToPdf(chart, options = {}) {
  * Chartsheets without an orderNo fall to the end, mirroring how Excel
  * treats sheets with missing tab positions.
  */
-async function excelWorkbookToPdf(workbook) {
-    const worksheetResults = await Promise.all((0, workbook_1.getWorksheets)(workbook).map(ws => convertSheet(ws, workbook)));
-    const chartsheetResults = await Promise.all((0, workbook_1.getChartsheets)(workbook).map(cs => convertChartsheet(cs, workbook)));
+async function excelWorkbookToPdf(workbook, options) {
+    const worksheetResults = await Promise.all((0, workbook_1.getWorksheets)(workbook).map(ws => convertSheet(ws, workbook, options)));
+    const chartsheetResults = await Promise.all((0, workbook_1.getChartsheets)(workbook).map(cs => convertChartsheet(cs, workbook, options)));
     const combined = [...worksheetResults, ...chartsheetResults];
     combined.sort((a, b) => (a.orderNo ?? Number.POSITIVE_INFINITY) - (b.orderNo ?? Number.POSITIVE_INFINITY));
     return {
@@ -196,7 +196,7 @@ async function excelWorkbookToPdf(workbook) {
 // =============================================================================
 // Sheet Conversion
 // =============================================================================
-async function convertSheet(ws, workbook) {
+async function convertSheet(ws, workbook, options) {
     const dimensions = (0, worksheet_1.getSheetDimensions)(ws);
     const hasData = dimensions && dimensions.top > 0 && dimensions.left > 0;
     const bounds = hasData
@@ -316,10 +316,22 @@ async function convertSheet(ws, workbook) {
                 }
                 : undefined,
             scale: ps.scale,
+            fitToPage: ps.fitToPage,
+            fitToWidth: ps.fitToWidth,
+            fitToHeight: ps.fitToHeight,
             printTitlesRow: ps.printTitlesRow,
+            printTitlesColumn: ps.printTitlesColumn,
             showGridLines: ps.showGridLines,
+            showRowColHeaders: ps.showRowColHeaders,
             printArea: ps.printArea,
-            firstPageNumber: ps.useFirstPageNumber === false ? undefined : ps.firstPageNumber
+            firstPageNumber: ps.useFirstPageNumber === false ? undefined : ps.firstPageNumber,
+            pageOrder: ps.pageOrder,
+            blackAndWhite: ps.blackAndWhite,
+            draft: ps.draft,
+            errors: ps.errors,
+            cellComments: ps.cellComments,
+            horizontalCentered: ps.horizontalCentered,
+            verticalCentered: ps.verticalCentered
         }
         : undefined;
     // Convert row/col breaks
@@ -328,9 +340,18 @@ async function convertSheet(ws, workbook) {
     // 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);
-    const charts = await collectCharts(ws);
-    const sparklineCharts = collectSparklineCharts(ws);
+    //
+    // Draft quality prints no graphics, so skip collection entirely rather than
+    // gathering (and rasterizing ChartEx layouts) only to drop the result during
+    // layout: draft exists to be cheap, and a rasterizer failure must not sink an
+    // export that would not have shown the graphic anyway. The precedence here
+    // mirrors `resolveOptions`; the layout engine still gates on the resolved
+    // flag, so this stays a pure optimization.
+    const comments = collectComments(ws);
+    const draftQuality = options?.draft ?? ws.pageSetup?.draft ?? false;
+    const images = draftQuality ? undefined : collectImages(ws, workbook);
+    const charts = draftQuality ? undefined : await collectCharts(ws);
+    const sparklineCharts = draftQuality ? undefined : collectSparklineCharts(ws);
     // Merge sparkline micro-charts with regular charts
     const allCharts = charts
         ? sparklineCharts
@@ -402,14 +423,91 @@ async function convertSheet(ws, workbook) {
         rows,
         merges,
         pageSetup,
-        headerFooter: convertHeaderFooter(ws, workbook),
+        headerFooter: convertHeaderFooter(ws, workbook, draftQuality),
         rowBreaks,
         colBreaks,
         images,
-        charts: allCharts
+        charts: allCharts,
+        comments
     };
 }
-function convertHeaderFooter(ws, workbook) {
+/**
+ * Collect every comment on a worksheet, in row-major order.
+ *
+ * Two sources are merged: classic notes stored on the cell (`_comment`, the
+ * VML-backed kind) and Office 365 threaded comments held on the sheet. Only the
+ * text and author are needed — the printed form is an end-of-sheet list, not a
+ * positioned box — so the VML geometry is deliberately ignored.
+ */
+function collectComments(ws) {
+    const collected = [];
+    for (const row of ws._rows ?? []) {
+        if (!row) {
+            continue;
+        }
+        for (const cell of row.cells ?? []) {
+            if (!cell) {
+                continue;
+            }
+            const note = (0, cell_1.cellComment)(cell);
+            const text = noteText(note?.note);
+            if (text) {
+                collected.push({
+                    ref: cell.address,
+                    text,
+                    author: note?.author,
+                    anchor: parseVmlAnchor(note?.note)
+                });
+            }
+        }
+    }
+    for (const entry of ws.threadedComments ?? []) {
+        const text = entry.comment.text?.trim();
+        if (text) {
+            collected.push({ ref: entry.ref, text, author: entry.comment.personId });
+        }
+    }
+    return collected.length > 0 ? collected : undefined;
+}
+/**
+ * Decode a VML comment anchor into fractional sheet coordinates.
+ *
+ * `<x:Anchor>` holds eight integers: for each edge a column/row index followed
+ * by an offset into it, measured in 1/68 of a column and 1/18 of a row (the
+ * reciprocals Excel uses when it writes the value). Returns `undefined` when the
+ * note has no anchor, so callers fall back to Excel's default placement.
+ */
+function parseVmlAnchor(note) {
+    if (!note || typeof note === "string" || typeof note.anchor !== "string") {
+        return undefined;
+    }
+    const parts = note.anchor.split(",").map(p => Number(p.trim()));
+    if (parts.length !== 8 || parts.some(n => !Number.isFinite(n))) {
+        return undefined;
+    }
+    const [l, lf, t, tf, r, rf, b, bf] = parts;
+    return {
+        left: l + lf / 68,
+        top: t + tf / 18,
+        right: r + rf / 68,
+        bottom: b + bf / 18
+    };
+}
+/** Flatten a note body, which may be plain text or a rich `NoteConfig`. */
+function noteText(note) {
+    if (typeof note === "string") {
+        return note.trim() || undefined;
+    }
+    if (note && typeof note === "object" && Array.isArray(note.texts)) {
+        const joined = note.texts
+            .map(t => (typeof t === "string" ? t : (t.text ?? "")))
+            .join("")
+            .trim();
+        return joined || undefined;
+    }
+    return undefined;
+}
+function convertHeaderFooter(ws, workbook, draftQuality = false) {
     const source = ws.headerFooter;
     const fields = [
         source.oddHeader,
@@ -419,7 +517,9 @@ function convertHeaderFooter(ws, workbook) {
         source.firstHeader,
         source.firstFooter
     ];
-    const images = convertHeaderFooterImages(ws, workbook);
+    // Draft quality prints no graphics, header pictures included, so skip
+    // collecting them rather than embedding XObjects nothing will draw.
+    const images = draftQuality ? [] : convertHeaderFooterImages(ws, workbook);
     if (!fields.some(Boolean) && images.length === 0) {
         return undefined;
     }
@@ -1258,7 +1358,7 @@ function chartAnchorRange(chart) {
             : 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`.
+        // (÷12700) 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
     };
@@ -1342,11 +1442,16 @@ const CHARTSHEET_RASTER_PX = { width: 1280, height: 720 };
  *   (matches what Excel prints for a chartsheet whose chart was deleted
  *   but the sheet kept).
  */
-async function convertChartsheet(cs, workbook) {
+async function convertChartsheet(cs, workbook, options) {
     const classicModel = (0, chartsheet_1.chartsheetChartModel)(cs);
     const chartExModel = (0, chartsheet_1.chartsheetChartExModel)(cs);
+    // Resolve draft before touching the chart: a ChartEx outside the vector
+    // whitelist would otherwise be rasterised at cost — and could fail — for a
+    // page that prints no graphics at all. Precedence mirrors `resolveOptions`.
+    const draftQuality = options?.draft ?? (0, chartsheet_1.chartsheetPageSetup)(cs)?.draft ?? false;
+    // Draft quality prints no graphics, so the chart is simply never built.
     let chart = {};
-    if (classicModel) {
+    if (!draftQuality && classicModel) {
         const model = classicModel;
         chart = {
             drawVector: (surface, rect) => {
@@ -1359,7 +1464,7 @@ async function convertChartsheet(cs, workbook) {
             }
         };
     }
-    else if (chartExModel) {
+    else if (!draftQuality && chartExModel) {
         if ((0, chart_ex_renderer_1.canRenderChartExAsVectorPdf)(chartExModel)) {
             const model = chartExModel;
             chart = {
@@ -1400,6 +1505,8 @@ async function convertChartsheet(cs, workbook) {
             orientation: ps?.orientation,
             paperSize: ps?.paperSize,
             showGridLines: false,
+            blackAndWhite: ps?.blackAndWhite,
+            draft: ps?.draft,
             firstPageNumber: ps?.useFirstPageNumber === false ? undefined : ps?.firstPageNumber,
             margins: margins
                 ? {
@@ -1421,7 +1528,7 @@ async function convertChartsheet(cs, workbook) {
         orientation,
         chart,
         pageSetup,
-        headerFooter: convertHeaderFooterModel((0, chartsheet_1.chartsheetModel)(cs).headerFooter, convertChartsheetHeaderImages((0, chartsheet_1.chartsheetModel)(cs).headerImages, workbook))
+        headerFooter: convertHeaderFooterModel((0, chartsheet_1.chartsheetModel)(cs).headerFooter, draftQuality ? [] : convertChartsheetHeaderImages((0, chartsheet_1.chartsheetModel)(cs).headerImages, workbook))
     };
 }
 function convertChartsheetHeaderImages(images, workbook) {

package/dist/cjs/modules/pdf/render/chart-surface.js

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createChartSurface = createChartSurface;
 const font_manager_1 = require("../font/font-manager.js");
 const page_renderer_1 = require("./page-renderer.js");
+const style_converter_1 = require("./style-converter.js");
 /**
  * Build a {@link PdfChartDrawingSurface} that forwards to the given content
  * stream. The returned surface is stateful — callers should not mix it with
@@ -31,38 +32,77 @@ const page_renderer_1 = require("./page-renderer.js");
  * @param alphaValues   Shared set that accumulates transparency values for
  *                      later `ExtGState` registration. The surface adds any
  *                      `color.a` values it observes to this set.
+ * @param grayscale     When true, every color the chart renderer emits is
+ *                      converted to grayscale. Charts bypass the cell style
+ *                      pipeline entirely — the chart engine pushes colors
+ *                      straight into this surface — so Excel's "Black and
+ *                      white" print option has to be applied right here.
  */
-function createChartSurface(stream, fontManager, alphaValues) {
+function createChartSurface(stream, fontManager, alphaValues, grayscale = false) {
+    /** Single choke point for every color entering the surface. */
+    const mapColor = (color) => grayscale && color ? (0, style_converter_1.toGrayscale)(color) : color;
     const applyAlpha = (color) => {
         if (color?.a !== undefined && color.a < 1) {
             alphaValues.add(color.a);
             stream.setGraphicsState((0, page_renderer_1.alphaGsName)(color.a));
         }
     };
-    const paintFillStroke = (options) => {
-        const { fill, stroke, lineWidth } = options;
+    /**
+     * Fill and/or stroke the path built by `buildPath`.
+     *
+     * `buildPath` is a closure rather than a pre-built path because a fill and a
+     * stroke with *different* opacities cannot share one graphics state: the
+     * alpha `ExtGState` sets `/ca` and `/CA` together, and `fillAndStroke()`
+     * paints both under whichever was applied last. In that case we paint in two
+     * passes and rebuild the path for the second one. (Within a single pass the
+     * unused half of the ExtGState is harmless — a fill-only pass never strokes.)
+     */
+    const paintFillStroke = (buildPath, options) => {
+        const { lineWidth, dashPattern } = options;
+        const fill = mapColor(options.fill);
+        const stroke = mapColor(options.stroke);
+        const applyDash = () => {
+            if (dashPattern && dashPattern.length > 0) {
+                stream.setDashPattern(dashPattern);
+            }
+        };
+        if (fill && stroke) {
+            const fillAlpha = fill.a ?? 1;
+            const strokeAlpha = stroke.a ?? 1;
+            if (fillAlpha !== strokeAlpha) {
+                stream.save();
+                buildPath();
+                stream.setFillColor(fill);
+                applyAlpha(fill);
+                stream.fill();
+                stream.restore();
+                stream.save();
+                buildPath();
+                stream.setStrokeColor(stroke);
+                applyAlpha(stroke);
+                applyDash();
+                if (lineWidth !== undefined) {
+                    stream.setLineWidth(lineWidth);
+                }
+                stream.stroke();
+                stream.restore();
+                return;
+            }
+        }
+        buildPath();
+        applyDash();
+        // Reaching here means either a single operation, or a fill and stroke that
+        // share one opacity — so one ExtGState describes both and no reset is
+        // needed (the differing case returned above, each pass in its own q/Q).
         if (fill) {
             stream.setFillColor(fill);
             applyAlpha(fill);
         }
         if (stroke) {
             stream.setStrokeColor(stroke);
-            // When fill applied a sub-1 alpha but stroke is fully opaque (no
-            // `a` field or `a >= 1`), we must explicitly restore opaque alpha
-            // so the stroke is not drawn with the fill's transparency. The
-            // ExtGState set by `applyAlpha(fill)` applies to both fill and
-            // stroke operations in PDF; without this reset the stroke leaks
-            // the fill's alpha.
-            const strokeNeedsAlpha = stroke.a !== undefined && stroke.a < 1;
-            const fillAppliedAlpha = fill?.a !== undefined && fill.a < 1;
-            if (strokeNeedsAlpha) {
+            if (!fill) {
                 applyAlpha(stroke);
             }
-            else if (fillAppliedAlpha) {
-                // Reset to fully opaque for the stroke
-                alphaValues.add(1);
-                stream.setGraphicsState((0, page_renderer_1.alphaGsName)(1));
-            }
             if (lineWidth !== undefined) {
                 stream.setLineWidth(lineWidth);
             }
@@ -84,13 +124,13 @@ function createChartSurface(stream, fontManager, alphaValues) {
         drawRect(options) {
             const { x, y, width, height, fill, stroke, lineWidth } = options;
             stream.save();
-            stream.rect(x, y, width, height);
-            paintFillStroke({ fill, stroke, lineWidth });
+            paintFillStroke(() => stream.rect(x, y, width, height), { fill, stroke, lineWidth });
             stream.restore();
             return this;
         },
         drawLine(options) {
-            const { x1, y1, x2, y2, color, lineWidth, dashPattern } = options;
+            const { x1, y1, x2, y2, lineWidth, dashPattern } = options;
+            const color = mapColor(options.color);
             stream.save();
             if (color) {
                 stream.setStrokeColor(color);
@@ -111,7 +151,7 @@ function createChartSurface(stream, fontManager, alphaValues) {
                 return this;
             }
             const fontSize = options.fontSize ?? 10;
-            const color = options.color ?? { r: 0, g: 0, b: 0 };
+            const color = mapColor(options.color ?? { r: 0, g: 0, b: 0 });
             const bold = options.bold ?? false;
             const italic = options.italic ?? false;
             const fontFamily = options.fontFamily ?? "Helvetica";
@@ -143,39 +183,38 @@ function createChartSurface(stream, fontManager, alphaValues) {
         drawCircle(options) {
             const { cx, cy, r, fill, stroke, lineWidth } = options;
             stream.save();
-            stream.circle(cx, cy, r);
-            paintFillStroke({ fill, stroke, lineWidth });
+            paintFillStroke(() => stream.circle(cx, cy, r), { fill, stroke, lineWidth });
             stream.restore();
             return this;
         },
         drawPath(ops, options) {
-            stream.save();
-            for (const op of ops) {
-                switch (op.op) {
-                    case "move":
-                        stream.moveTo(op.x, op.y);
-                        break;
-                    case "line":
-                        stream.lineTo(op.x, op.y);
-                        break;
-                    case "curve":
-                        stream.curveTo(op.x1, op.y1, op.x2, op.y2, op.x3, op.y3);
-                        break;
-                    case "close":
-                        stream.closePath();
-                        break;
+            const buildPath = () => {
+                for (const op of ops) {
+                    switch (op.op) {
+                        case "move":
+                            stream.moveTo(op.x, op.y);
+                            break;
+                        case "line":
+                            stream.lineTo(op.x, op.y);
+                            break;
+                        case "curve":
+                            stream.curveTo(op.x1, op.y1, op.x2, op.y2, op.x3, op.y3);
+                            break;
+                        case "close":
+                            stream.closePath();
+                            break;
+                    }
                 }
-            }
-            if (options?.closePath) {
-                stream.closePath();
-            }
-            if (options?.dashPattern && options.dashPattern.length > 0) {
-                stream.setDashPattern(options.dashPattern);
-            }
-            paintFillStroke({
+                if (options?.closePath) {
+                    stream.closePath();
+                }
+            };
+            stream.save();
+            paintFillStroke(buildPath, {
                 fill: options?.fill,
                 stroke: options?.stroke,
-                lineWidth: options?.lineWidth
+                lineWidth: options?.lineWidth,
+                dashPattern: options?.dashPattern
             });
             stream.restore();
             return this;

package/dist/cjs/modules/pdf/render/constants.js

@@ -6,7 +6,7 @@
  * use exactly the same values, preventing clipped or overlapping content.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PX_TO_PT = exports.MAX_DIGIT_WIDTH_PX = exports.INDENT_WIDTH = exports.LINE_HEIGHT_FACTOR = exports.CELL_PADDING_V = exports.CELL_PADDING_H = void 0;
+exports.PAGE_NUMBER_BAND_HEIGHT = exports.SHEET_NAME_BAND_HEIGHT = exports.COLUMN_FIT_EPSILON = exports.COMMENT_MARKER_COLOR = exports.COMMENT_BORDER = exports.COMMENT_FILL = exports.COMMENT_MARKER_SIZE = exports.FIT_MIN_SCALE = exports.HEADING_TEXT = exports.HEADING_RULE = exports.HEADING_FILL = exports.HEADING_PADDING = exports.HEADING_FONT_SIZE = exports.PX_TO_PT = exports.MAX_DIGIT_WIDTH_PX = exports.INDENT_WIDTH = exports.LINE_HEIGHT_FACTOR = exports.CELL_PADDING_V = exports.CELL_PADDING_H = void 0;
 /** Horizontal cell padding in points (left + right = 2 × CELL_PADDING_H). */
 exports.CELL_PADDING_H = 3;
 /** Vertical cell padding in points (top + bottom = 2 × CELL_PADDING_V). */
@@ -31,3 +31,48 @@ exports.INDENT_WIDTH = 10;
  */
 exports.MAX_DIGIT_WIDTH_PX = 7;
 exports.PX_TO_PT = 72 / 96; // 0.75
+/**
+ * Font size of the printed row-number / column-letter headings, in points.
+ *
+ * Deliberately independent of the grid's print scale: headings are a reading
+ * aid rather than content, so a fixed size stays legible even when the grid is
+ * shrunk to fit, and lets the layout reserve exactly the space it draws.
+ */
+exports.HEADING_FONT_SIZE = 8;
+/** Padding around a heading label, in points (applied on both sides). */
+exports.HEADING_PADDING = 3;
+/** Background shade and rule color of the heading bands. */
+exports.HEADING_FILL = { r: 0.94, g: 0.94, b: 0.94 };
+exports.HEADING_RULE = { r: 0.6, g: 0.6, b: 0.6 };
+exports.HEADING_TEXT = { r: 0.2, g: 0.2, b: 0.2 };
+/**
+ * Lower bound when solving "fit to N pages", matching the 10% floor of Excel's
+ * Page Setup scaling. A target that is unreachable at this scale — typically
+ * because manual page breaks force more pages than requested — yields more than
+ * N pages rather than shrinking the grid into illegibility.
+ */
+exports.FIT_MIN_SCALE = 0.1;
+/**
+ * Side length of the red corner marker Excel draws on a commented cell, in
+ * points at 100% scale.
+ */
+exports.COMMENT_MARKER_SIZE = 4;
+/** Comment box fill, border and text colors, matching Excel's note styling. */
+exports.COMMENT_FILL = { r: 1, g: 1, b: 0.88 };
+exports.COMMENT_BORDER = { r: 0.4, g: 0.4, b: 0.4 };
+exports.COMMENT_MARKER_COLOR = { r: 0.8, g: 0, b: 0 };
+/**
+ * Overflow tolerance when packing columns into a page, in points.
+ *
+ * Scaled point widths accumulate rounding error, so a column that mathematically
+ * fits can measure a hair too wide. Rows need no such slack because their
+ * heights are not derived from a character-width conversion.
+ */
+exports.COLUMN_FIT_EPSILON = 0.01;
+/**
+ * Height of the bands reserved for the fallback sheet-name header and
+ * page-number footer, in points. Excel header/footers use their own margins;
+ * these are the simple `showSheetNames` / `showPageNumbers` bands.
+ */
+exports.SHEET_NAME_BAND_HEIGHT = 20;
+exports.PAGE_NUMBER_BAND_HEIGHT = 20;