documonster 0.7.0 → 0.8.0

package/dist/browser/modules/pdf/types.d.ts

@@ -122,11 +122,52 @@ export interface PdfPageSetupData {
         header?: number;
         footer?: number;
     };
+    /** Excel's scaling percentage (10–400, where 100 = actual size). */
     scale?: number;
+    /**
+     * Whether Excel's "Fit to N page(s) wide by M tall" scaling mode is active
+     * (`<sheetPr><pageSetUpPr fitToPage="1"/></sheetPr>`). When true,
+     * {@link fitToWidth} / {@link fitToHeight} drive the scale and
+     * {@link scale} is ignored — the two are mutually exclusive in Excel's UI.
+     */
+    fitToPage?: boolean;
+    /** Pages wide to fit into. `0` means "unlimited" (no width constraint). */
+    fitToWidth?: number;
+    /** Pages tall to fit into. `0` means "unlimited" (no height constraint). */
+    fitToHeight?: number;
     printTitlesRow?: string;
+    /** Repeated columns, e.g. `"A:B"` or `"A"` (Excel's "Columns to repeat at left"). */
+    printTitlesColumn?: string;
     showGridLines?: boolean;
+    /** Print row numbers and column letters (`<printOptions headings="1"/>`). */
+    showRowColHeaders?: boolean;
     printArea?: string;
     firstPageNumber?: number;
+    /**
+     * Order in which pages of a multi-page sheet are emitted.
+     * Excel's default is `"downThenOver"`.
+     */
+    pageOrder?: string;
+    /** Render the sheet without color (Excel's "Black and white" print option). */
+    blackAndWhite?: boolean;
+    /** Draft quality — skips graphics (images and charts). */
+    draft?: boolean;
+    /** How error values are printed: `displayed` | `blank` | `dash` | `NA`. */
+    errors?: string;
+    /** How comments print: `None` | `asDisplayed` | `atEnd`. */
+    cellComments?: string;
+    /**
+     * Excel's "Center on page → Horizontally" print option
+     * (`<printOptions horizontalCentered="1"/>`). When false/absent the
+     * printed grid starts at the left margin.
+     */
+    horizontalCentered?: boolean;
+    /**
+     * Excel's "Center on page → Vertically" print option
+     * (`<printOptions verticalCentered="1"/>`). When false/absent the
+     * printed grid starts at the top margin.
+     */
+    verticalCentered?: boolean;
 }
 export type PdfHeaderFooterField = "pageNumber" | "pageCount" | "sheetName" | "fileName" | "filePath" | "date" | "time" | "image";
 export interface PdfHeaderFooterRun {
@@ -359,6 +400,8 @@ export interface PdfSheetData {
     images?: PdfSheetImage[];
     /** Embedded charts (classic + ChartEx) */
     charts?: PdfSheetChart[];
+    /** Cell comments and notes, in row-major order. */
+    comments?: PdfSheetComment[];
 }
 /**
  * A chartsheet — a single-chart "sheet" with no cell grid.
@@ -440,6 +483,68 @@ export declare const PageSizes: Record<PageSizeName, PdfPageSize>;
  * Page orientation for PDF export.
  */
 export type PdfOrientation = "portrait" | "landscape";
+/**
+ * Order in which the pages of a multi-page sheet are emitted, mirroring
+ * Excel's "Page order" setting.
+ */
+export type PdfPageOrder = "downThenOver" | "overThenDown";
+/**
+ * How cells holding an error value are printed, mirroring Excel's
+ * "Cell errors as" setting.
+ */
+export type PdfCellErrorMode = "displayed" | "blank" | "dash" | "NA";
+/**
+ * How cell comments are printed, mirroring Excel's "Comments and notes"
+ * print option.
+ */
+export type PdfCellCommentMode = "none" | "atEnd" | "asDisplayed";
+/**
+ * Comment box placement, in fractional sheet coordinates.
+ *
+ * Excel stores this as a VML anchor: eight integers giving a column/row plus an
+ * offset in 1/68 of a column and 1/18 of a row. Those are pre-divided here so
+ * the layout engine only has to interpolate against its own track geometry.
+ * All values are 0-based, matching the VML convention.
+ */
+export interface PdfCommentAnchor {
+    /** Left edge, in columns. `2.5` is halfway across the third column. */
+    left: number;
+    /** Top edge, in rows. */
+    top: number;
+    /** Right edge, in columns. */
+    right: number;
+    /** Bottom edge, in rows. */
+    bottom: number;
+}
+/** A single printed cell comment. */
+export interface PdfSheetComment {
+    /** Cell address the comment is attached to, e.g. `"B7"`. */
+    ref: string;
+    /** Plain-text body. */
+    text: string;
+    /** Author, when the source recorded one. */
+    author?: string;
+    /**
+     * Where the comment box sits on the sheet, when the source recorded a VML
+     * anchor. Consumed by `cellComments: "asDisplayed"`; absent comments fall back
+     * to Excel's default offset from their cell.
+     */
+    anchor?: PdfCommentAnchor;
+}
+/**
+ * An inclusive band of repeated title rows or columns, in absolute 1-based
+ * sheet coordinates.
+ *
+ * Absolute rather than a count, because Excel's "Rows/Columns to repeat" are
+ * independent of the print area: a sheet printing `C5:H50` can still repeat
+ * `A:B` at the left of every page.
+ */
+export interface PdfRepeatBand {
+    /** First row/column of the band (1-based, inclusive). */
+    first: number;
+    /** Last row/column of the band (1-based, inclusive). */
+    last: number;
+}
 /**
  * Excel header/footer rendering options.
  *
@@ -497,16 +602,116 @@ export interface PdfExportOptions {
      */
     ignorePrintArea?: boolean;
     /**
-     * Whether to auto-fit column widths to page width.
-     * When true, columns are scaled proportionally to fit the page.
+     * Whether to shrink column widths so the grid fits the page width.
+     * Never enlarges — content narrower than the page is left at actual size,
+     * matching Excel's fit-to-page behaviour.
+     *
+     * This is the fallback used when neither the caller nor the sheet expresses a
+     * fit-to-N or percentage scaling intent, so a sheet asking for 80% is not
+     * shrunk twice. Passing it explicitly always wins, including over the sheet's
+     * own fit-to-N mode.
+     *
+     * Note that {@link scale} is a *multiplier applied on top* of this and does
+     * not disable it: `{ scale: 0.8 }` on an over-wide grid yields
+     * `0.8 × fit-to-width`. Pass `fitToPage: false` alongside it for a plain 80%.
      * @default true
      */
     fitToPage?: boolean;
     /**
-     * Scale factor (0.1 to 3.0). Applied after fitToPage.
-     * @default 1.0
+     * Scale factor (0.1 to 4.0), where `1.0` is actual size, multiplied with any
+     * fit-to-page shrinking (see {@link fitToPage}). Overrides the sheet's
+     * `pageSetup.scale`, which Excel stores as a 10–400 percentage.
+     *
+     * When omitted, the sheet's own scaling is used; see {@link fitToPage}.
      */
     scale?: number;
+    /**
+     * Shrink the grid so it spans at most this many pages horizontally,
+     * mirroring Excel's "Fit to N page(s) wide". `0` removes the constraint.
+     *
+     * Like Excel, this only ever shrinks. When omitted, the sheet's
+     * `pageSetup.fitToWidth` is used if its `fitToPage` mode is on.
+     */
+    fitToWidth?: number;
+    /**
+     * Shrink the grid so it spans at most this many pages vertically,
+     * mirroring Excel's "Fit to M page(s) tall". `0` removes the constraint.
+     *
+     * Like Excel, this only ever shrinks. When omitted, the sheet's
+     * `pageSetup.fitToHeight` is used if its `fitToPage` mode is on.
+     */
+    fitToHeight?: number;
+    /**
+     * Number of leading columns to repeat on every horizontal page, the
+     * counterpart of {@link repeatRows}.
+     *
+     * When omitted, the sheet's `pageSetup.printTitlesColumn` ("Columns to
+     * repeat at left", e.g. `"A:B"`) is used.
+     * @default false
+     */
+    repeatCols?: number | false;
+    /**
+     * Print row numbers and column letters around the grid, mirroring Excel's
+     * "Row and column headings" print option.
+     *
+     * When omitted, the sheet's `pageSetup.showRowColHeaders` is used.
+     * @default false
+     */
+    showRowColHeaders?: boolean;
+    /**
+     * Order in which the pages of a multi-page sheet are emitted, mirroring
+     * Excel's "Page order". `"downThenOver"` finishes each column band top to
+     * bottom before moving right; `"overThenDown"` finishes each row band left
+     * to right before moving down.
+     *
+     * When omitted, the sheet's `pageSetup.pageOrder` is used.
+     * @default "downThenOver"
+     */
+    pageOrder?: PdfPageOrder;
+    /**
+     * Render vector content without color, mirroring Excel's "Black and white"
+     * print option. Colors are converted to their luminance-preserving grayscale
+     * equivalent, preserving opacity.
+     *
+     * Covers vector content (cell text, fills and borders, gridlines, the
+     * row/column heading bands, chart vectors, `&K`-colored header/footer runs and
+     * text watermarks) as well as raster content: PNG samples are converted to a
+     * single luma component, and JPEG keeps its DCTDecode data but is reinterpreted
+     * through a `/DeviceN` luma color space, so neither needs an overlay and
+     * transparency is preserved.
+     *
+     * When omitted, the sheet's `pageSetup.blackAndWhite` is used.
+     * @default false
+     */
+    blackAndWhite?: boolean;
+    /**
+     * Draft quality — omit images and charts, mirroring Excel's "Draft quality"
+     * print option.
+     *
+     * When omitted, the sheet's `pageSetup.draft` is used.
+     * @default false
+     */
+    draft?: boolean;
+    /**
+     * How cells holding an error value are printed, mirroring Excel's
+     * "Cell errors as" print option.
+     *
+     * When omitted, the sheet's `pageSetup.errors` is used.
+     * @default "displayed"
+     */
+    errors?: PdfCellErrorMode;
+    /**
+     * Whether cell comments and notes are printed, mirroring Excel's
+     * "Comments and notes" print option.
+     *
+     * `"atEnd"` appends a list of every comment after the sheet's pages.
+     * `"asDisplayed"` draws each comment as a box where it sits on the sheet,
+     * plus the red corner marker Excel puts on the commented cell.
+     *
+     * When omitted, the sheet's `pageSetup.cellComments` is used.
+     * @default "none"
+     */
+    cellComments?: PdfCellCommentMode;
     /**
      * Whether to show grid lines on the page.
      * @default false
@@ -517,6 +722,24 @@ export interface PdfExportOptions {
      * @default "FFD0D0D0"
      */
     gridLineColor?: string;
+    /**
+     * Center the printed grid horizontally within the page's content area,
+     * mirroring Excel's "Page Setup → Margins → Center on page → Horizontally".
+     *
+     * When omitted, the source sheet's `pageSetup.horizontalCentered` is used;
+     * if that is unset too, content starts at the left margin.
+     * @default false
+     */
+    horizontalCentered?: boolean;
+    /**
+     * Center the printed grid vertically within the page's content area,
+     * mirroring Excel's "Page Setup → Margins → Center on page → Vertically".
+     *
+     * When omitted, the source sheet's `pageSetup.verticalCentered` is used;
+     * if that is unset too, content starts at the top margin.
+     * @default false
+     */
+    verticalCentered?: boolean;
     /**
      * Whether to repeat row headers on each page.
      * Can be a number (row count from top) or false to disable.
@@ -863,9 +1086,22 @@ export interface ResolvedPdfOptions {
     ignorePrintArea: boolean;
     fitToPage: boolean;
     scale: number;
+    /** Pages wide to shrink into; `0` means unconstrained. */
+    fitToWidth: number;
+    /** Pages tall to shrink into; `0` means unconstrained. */
+    fitToHeight: number;
     showGridLines: boolean;
     gridLineColor: PdfColor;
-    repeatRows: number | false;
+    showRowColHeaders: boolean;
+    horizontalCentered: boolean;
+    verticalCentered: boolean;
+    pageOrder: PdfPageOrder;
+    blackAndWhite: boolean;
+    draft: boolean;
+    errors: PdfCellErrorMode;
+    cellComments: PdfCellCommentMode;
+    repeatRows: PdfRepeatBand | false;
+    repeatCols: PdfRepeatBand | false;
     defaultFontFamily: string;
     defaultFontSize: number;
     showSheetNames: boolean;
@@ -1040,8 +1276,51 @@ export interface LayoutPage {
     charts: LayoutChart[];
     /** Scale factor applied to this page (for fitToPage) */
     scaleFactor: number;
+    /**
+     * Geometry of the printed row/column heading bands, when
+     * {@link ResolvedPdfOptions.showRowColHeaders} is on. Absent otherwise.
+     */
+    headings?: LayoutHeadings;
+    /**
+     * Comment boxes to draw on this page, for
+     * `cellComments: "asDisplayed"`. Empty otherwise.
+     */
+    commentBoxes?: LayoutCommentBox[];
     headerFooter?: PdfHeaderFooterData;
 }
+/**
+ * A comment box positioned on the sheet, as Excel's "Comments: as displayed"
+ * prints it, together with the corner marker on the commented cell.
+ */
+export interface LayoutCommentBox {
+    /** Box outline in page coordinates. */
+    rect: PdfRect;
+    /** Comment body, already prefixed with the author when one is known. */
+    text: string;
+    /** Font size in points. */
+    fontSize: number;
+    /**
+     * Corner marker on the commented cell, when that cell is on this page. Excel
+     * draws a small red triangle in its top-right corner.
+     */
+    marker?: {
+        x: number;
+        y: number;
+        size: number;
+    };
+}
+/**
+ * Row-number gutter and column-letter band geometry for a page printed with
+ * Excel's "Row and column headings" option.
+ */
+export interface LayoutHeadings {
+    /** Width of the row-number gutter to the left of the grid, in points. */
+    gutterWidth: number;
+    /** Height of the column-letter band above the grid, in points. */
+    bandHeight: number;
+    /** Font size used for the heading labels, in points. */
+    fontSize: number;
+}
 /**
  * A positioned image on a PDF page.
  */

package/dist/cjs/modules/pdf/builder/image-utils.js

@@ -82,41 +82,90 @@ function parseJpegDimensions(data) {
  * Write an image XObject (JPEG or PNG) to the writer.
  * Returns the allocated object number.
  */
-function writeImageXObject(writer, data, format) {
+function writeImageXObject(writer, data, format, grayscale = false) {
     if (format === "png") {
-        return writePngImageXObject(writer, data);
+        return writePngImageXObject(writer, data, grayscale);
     }
-    return writeJpegImageXObject(writer, data);
+    return writeJpegImageXObject(writer, data, grayscale);
 }
 /**
- * Write a JPEG image using DCTDecode (raw JPEG data embedded directly).
+ * Write the PostScript calculator function that converts an RGB triple to its
+ * Rec. 601 luma, and return its object number.
+ *
+ * Used as the tint transform of a `/DeviceN` space so a JPEG can be recoloured
+ * without decoding it: the samples stay untouched and the consumer applies the
+ * transform per pixel. Unlike painting a blend on top, this cannot darken
+ * transparent areas, because it *is* the color space rather than an overlay.
  */
-function writeJpegImageXObject(writer, data) {
+function writeLumaTintTransform(writer) {
     const objNum = writer.allocObject();
+    const dict = new pdf_object_1.PdfDict()
+        .set("FunctionType", "4")
+        .set("Domain", "[0 1 0 1 0 1]")
+        .set("Range", "[0 1]");
+    // Stack on entry is R G B (B on top):
+    //   0.114 mul  -> R G 0.114B
+    //   exch       -> R 0.114B G
+    //   0.587 mul  -> R 0.114B 0.587G
+    //   add        -> R (0.114B + 0.587G)
+    //   exch       -> (0.114B + 0.587G) R
+    //   0.299 mul  -> (0.114B + 0.587G) 0.299R
+    //   add        -> luma
+    const program = "{ 0.114 mul exch 0.587 mul add exch 0.299 mul add }";
+    writer.addStreamObject(objNum, dict, new TextEncoder().encode(program));
+    return objNum;
+}
+/**
+ * Write a JPEG image using DCTDecode (raw JPEG data embedded directly).
+ */
+function writeJpegImageXObject(writer, data, grayscale = false) {
     const dims = parseJpegDimensions(data);
+    // Grayscale without a JPEG decoder: keep the DCTDecode samples and reinterpret
+    // the three components through a `/DeviceN` space whose tint transform is the
+    // luma formula. Component count still matches the JPEG, as PDF requires.
+    const tintRef = grayscale ? writeLumaTintTransform(writer) : undefined;
+    const objNum = writer.allocObject();
     const dict = new pdf_object_1.PdfDict()
         .set("Type", "/XObject")
         .set("Subtype", "/Image")
         .set("Width", (0, pdf_object_1.pdfNumber)(dims.width))
         .set("Height", (0, pdf_object_1.pdfNumber)(dims.height))
-        .set("ColorSpace", "/DeviceRGB")
+        .set("ColorSpace", tintRef === undefined
+        ? "/DeviceRGB"
+        : `[/DeviceN [/C1 /C2 /C3] /DeviceGray ${(0, pdf_object_1.pdfRef)(tintRef)}]`)
         .set("BitsPerComponent", "8")
         .set("Filter", "/DCTDecode");
     writer.addStreamObject(objNum, dict, data);
     return objNum;
 }
+/** Rec. 601 luma of an 8-bit RGB triple. */
+function lumaByte(r, g, b) {
+    return Math.round(0.299 * r + 0.587 * g + 0.114 * b);
+}
 /**
  * Write a PNG image: decode to raw RGB, create SMask for alpha if needed.
  */
-function writePngImageXObject(writer, data) {
+function writePngImageXObject(writer, data, grayscale = false) {
     const png = (0, png_decoder_1.decodePng)(data);
     const objNum = writer.allocObject();
+    // PNG is already decoded to raw samples here, so grayscale is a real pixel
+    // conversion: collapse RGB to one luma component and switch to DeviceGray.
+    // The alpha channel lives in a separate SMask and is untouched, so transparent
+    // regions stay transparent.
+    let pixels = png.pixels;
+    if (grayscale) {
+        const gray = new Uint8Array(png.width * png.height);
+        for (let i = 0, p = 0; i < gray.length; i++, p += 3) {
+            gray[i] = lumaByte(pixels[p], pixels[p + 1], pixels[p + 2]);
+        }
+        pixels = gray;
+    }
     const dict = new pdf_object_1.PdfDict()
         .set("Type", "/XObject")
         .set("Subtype", "/Image")
         .set("Width", (0, pdf_object_1.pdfNumber)(png.width))
         .set("Height", (0, pdf_object_1.pdfNumber)(png.height))
-        .set("ColorSpace", "/DeviceRGB")
+        .set("ColorSpace", grayscale ? "/DeviceGray" : "/DeviceRGB")
         .set("BitsPerComponent", (0, pdf_object_1.pdfNumber)(png.bitsPerComponent));
     if (png.alpha) {
         const smaskObjNum = writer.allocObject();
@@ -130,6 +179,6 @@ function writePngImageXObject(writer, data) {
         writer.addStreamObject(smaskObjNum, smaskDict, png.alpha);
         dict.set("SMask", (0, pdf_object_1.pdfRef)(smaskObjNum));
     }
-    writer.addStreamObject(objNum, dict, png.pixels);
+    writer.addStreamObject(objNum, dict, pixels);
     return objNum;
 }

package/dist/cjs/modules/pdf/core/pdf-writer.js

@@ -168,6 +168,9 @@ class PdfWriter {
             .set("MediaBox", mediaBox)
             .set("Contents", contentsValue)
             .set("Resources", (0, pdf_object_1.pdfRef)(options.resourcesRef));
+        if (options.transparencyGroup) {
+            dict.set("Group", "<< /S /Transparency /CS /DeviceRGB /I false /K false >>");
+        }
         if (options.annotRefs && options.annotRefs.length > 0) {
             dict.set("Annots", "[" + options.annotRefs.map(r => (0, pdf_object_1.pdfRef)(r)).join(" ") + "]");
         }