@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/browser/modules/pdf/font/font-manager.d.ts

@@ -38,6 +38,15 @@ export declare class FontManager {
     private nextEmbeddedId;
     private type3CodePoints;
     private _type3Result;
+    /**
+     * Every distinct unknown font family passed to `resolveFont` since this
+     * manager was constructed. A "family" counts as unknown when it isn't
+     * in `FONT_FAMILY_MAP` and isn't the canonical "helvetica"/"times"/
+     * "courier" identifier. Populated as a set so a document that repeats
+     * the same missing family across hundreds of text runs still produces
+     * a single diagnostic.
+     */
+    private _unknownFontFamilies;
     /**
      * Register an embedded TrueType font for use.
      * When set, all text rendering uses this font instead of standard fonts.
@@ -47,6 +56,22 @@ export declare class FontManager {
      * Check if an embedded font is available.
      */
     hasEmbeddedFont(): boolean;
+    /**
+     * Read-only view of the non-WinAnsi code points encountered so far when
+     * no font is embedded. Used by callers (`PdfDocumentBuilder.build()`)
+     * to decide whether to auto-discover a system font before the Type3
+     * fallback kicks in. Returns a defensive copy so consumers cannot
+     * mutate the internal set.
+     */
+    getType3CodePoints(): Set<number>;
+    /**
+     * Read-only view of the font families `resolveFont` saw but could not
+     * map to a standard Type1 (Helvetica/Times/Courier) base. Consumers
+     * use this to emit one diagnostic per distinct missing family at
+     * build time rather than one per text run. The set is deduplicated
+     * and preserves the exact casing the caller supplied.
+     */
+    getUnknownFontFamilies(): Set<string>;
     /**
      * Get the embedded font's resource name (if registered).
      */

package/dist/browser/modules/pdf/font/font-manager.js

@@ -125,6 +125,16 @@ export class FontManager {
         // --- Type3 fallback font tracking ---
         this.type3CodePoints = new Set();
         this._type3Result = null;
+        // --- Diagnostic tracking (consumed by writers that surface warnings) ---
+        /**
+         * Every distinct unknown font family passed to `resolveFont` since this
+         * manager was constructed. A "family" counts as unknown when it isn't
+         * in `FONT_FAMILY_MAP` and isn't the canonical "helvetica"/"times"/
+         * "courier" identifier. Populated as a set so a document that repeats
+         * the same missing family across hundreds of text runs still produces
+         * a single diagnostic.
+         */
+        this._unknownFontFamilies = new Set();
         /** Stored after writeFontResources is called */
         this._embeddedResult = null;
     }
@@ -146,6 +156,26 @@ export class FontManager {
     hasEmbeddedFont() {
         return this.embeddedFont !== null;
     }
+    /**
+     * Read-only view of the non-WinAnsi code points encountered so far when
+     * no font is embedded. Used by callers (`PdfDocumentBuilder.build()`)
+     * to decide whether to auto-discover a system font before the Type3
+     * fallback kicks in. Returns a defensive copy so consumers cannot
+     * mutate the internal set.
+     */
+    getType3CodePoints() {
+        return new Set(this.type3CodePoints);
+    }
+    /**
+     * Read-only view of the font families `resolveFont` saw but could not
+     * map to a standard Type1 (Helvetica/Times/Courier) base. Consumers
+     * use this to emit one diagnostic per distinct missing family at
+     * build time rather than one per text run. The set is deduplicated
+     * and preserves the exact casing the caller supplied.
+     */
+    getUnknownFontFamilies() {
+        return new Set(this._unknownFontFamilies);
+    }
     /**
      * Get the embedded font's resource name (if registered).
      */
@@ -203,6 +233,15 @@ export class FontManager {
         if (this.embeddedFont) {
             return this.embeddedResourceName;
         }
+        // Record unknown families so writers can emit a single diagnostic
+        // at build time instead of spamming one warning per text run.
+        // The canonical base-name keys are kept in FONT_FAMILY_MAP; anything
+        // not present will `?? "Helvetica"` in `resolveBaseFont` — that's the
+        // trigger for a "family not recognised" diagnostic.
+        const lowerKey = fontFamily.toLowerCase().trim();
+        if (lowerKey && FONT_FAMILY_MAP[lowerKey] === undefined) {
+            this._unknownFontFamilies.add(fontFamily);
+        }
         const pdfFontName = resolvePdfFontName(fontFamily, bold, italic);
         return this.ensureFont(pdfFontName);
     }

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

@@ -43,7 +43,10 @@
 /** Standalone PDF generation — accepts plain arrays, sheet objects, or workbooks. */
 export { pdf } from "./pdf.js";
 /** Excel-to-PDF conversion — accepts an Excel Workbook instance. */
-export { excelToPdf } from "./excel-bridge.js";
+export { excelToPdf, chartToPdf, type ChartToPdfOptions } from "./excel-bridge.js";
+/** Word-to-PDF conversion — accepts a DocxDocument. */
+export { docxToPdf } from "./word-bridge.js";
+export type { DocxToPdfOptions } from "./word-bridge.js";
 /** Read a PDF file and extract text, images, and metadata. */
 export { readPdf } from "./reader/pdf-reader.js";
 /** Build PDFs with free text positioning, vector drawing, and images. */
@@ -63,7 +66,7 @@ export type { PdfAnnotation, PdfRect } from "./reader/annotation-extractor.js";
 export type { PdfFormField, PdfFormFieldType } from "./reader/form-extractor.js";
 export type { PdfBookmark } from "./reader/bookmark-extractor.js";
 export type { PdfTable, PdfTableRow, PdfTableCell } from "./reader/table-extractor.js";
-export type { PageOptions, DrawTextOptions, DrawRectOptions, DrawCircleOptions, DrawEllipseOptions, DrawLineOptions, DrawPathOptions, DrawImageOptions, DocumentMetadata, PathOp, TocOptions, AnnotationType, AnnotationOptions, TextMarkupAnnotationOptions, TextAnnotationOptions, FreeTextAnnotationOptions, StampAnnotationOptions, FormFieldOptions, TextFieldOptions, CheckboxOptions, DropdownOptions, RadioGroupOptions, PdfSignatureOptions } from "./builder/document-builder.js";
+export type { PageOptions, DrawSvgOptions, DrawTextOptions, DrawRectOptions, DrawCircleOptions, DrawEllipseOptions, DrawLineOptions, DrawPathOptions, DrawImageOptions, DocumentMetadata, PathOp, TocOptions, AnnotationType, AnnotationOptions, TextMarkupAnnotationOptions, TextAnnotationOptions, FreeTextAnnotationOptions, StampAnnotationOptions, FormFieldOptions, TextFieldOptions, CheckboxOptions, DropdownOptions, RadioGroupOptions, PdfSignatureOptions } from "./builder/document-builder.js";
 export type { LoadOptions } from "./builder/pdf-editor.js";
 export type { SignatureVerificationResult, CmsSignedData, SignOptions, Asn1Node } from "./core/digital-signature.js";
 export { PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./errors.js";

package/dist/browser/modules/pdf/index.js

@@ -46,7 +46,9 @@
 /** Standalone PDF generation — accepts plain arrays, sheet objects, or workbooks. */
 export { pdf } from "./pdf.js";
 /** Excel-to-PDF conversion — accepts an Excel Workbook instance. */
-export { excelToPdf } from "./excel-bridge.js";
+export { excelToPdf, chartToPdf } from "./excel-bridge.js";
+/** Word-to-PDF conversion — accepts a DocxDocument. */
+export { docxToPdf } from "./word-bridge.js";
 // =============================================================================
 // Public API — Reading
 // =============================================================================

package/dist/browser/modules/pdf/render/chart-surface.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Adapter that exposes a {@link PdfChartDrawingSurface} on top of a raw
+ * {@link PdfContentStream}, letting the page-level exporter forward a chart's
+ * vector drawing callback into the same stream that renders the spreadsheet
+ * cells.
+ *
+ * Why this exists: the `chartToPdf` helper in `excel-bridge.ts` renders a
+ * single chart onto a `PdfDocumentBuilder` page (which natively implements
+ * the chart surface). For workbook-level `excelToPdf`, rendering happens via
+ * `pdf-exporter.ts` + `PdfContentStream`, which predate the chart surface.
+ * The adapter bridges the two worlds so a chart can be drawn at any
+ * `(x, y, width, height)` rect on an already-populated page without
+ * refactoring the exporter pipeline.
+ *
+ * All coordinates are PDF points with **bottom-left origin** — matching the
+ * convention the chart renderer emits after its internal Y-flip (see
+ * `translateScene` in `@excel/chart/chart-renderer.ts`).
+ */
+import type { PdfContentStream } from "../core/pdf-stream.js";
+import type { FontManager } from "../font/font-manager.js";
+import type { PdfChartDrawingSurface } from "../types.js";
+/**
+ * Build a {@link PdfChartDrawingSurface} that forwards to the given content
+ * stream. The returned surface is stateful — callers should not mix it with
+ * direct stream mutations for the duration of chart rendering.
+ *
+ * @param stream        Content stream receiving the drawing operators.
+ * @param fontManager   Font manager used for text layout and Type3 fallback.
+ * @param alphaValues   Shared set that accumulates transparency values for
+ *                      later `ExtGState` registration. The surface adds any
+ *                      `color.a` values it observes to this set.
+ */
+export declare function createChartSurface(stream: PdfContentStream, fontManager: FontManager, alphaValues: Set<number>): PdfChartDrawingSurface;

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

@@ -0,0 +1,200 @@
+/**
+ * Adapter that exposes a {@link PdfChartDrawingSurface} on top of a raw
+ * {@link PdfContentStream}, letting the page-level exporter forward a chart's
+ * vector drawing callback into the same stream that renders the spreadsheet
+ * cells.
+ *
+ * Why this exists: the `chartToPdf` helper in `excel-bridge.ts` renders a
+ * single chart onto a `PdfDocumentBuilder` page (which natively implements
+ * the chart surface). For workbook-level `excelToPdf`, rendering happens via
+ * `pdf-exporter.ts` + `PdfContentStream`, which predate the chart surface.
+ * The adapter bridges the two worlds so a chart can be drawn at any
+ * `(x, y, width, height)` rect on an already-populated page without
+ * refactoring the exporter pipeline.
+ *
+ * All coordinates are PDF points with **bottom-left origin** — matching the
+ * convention the chart renderer emits after its internal Y-flip (see
+ * `translateScene` in `@excel/chart/chart-renderer.ts`).
+ */
+import { resolvePdfFontName } from "../font/font-manager.js";
+import { alphaGsName, emitTextWithMatrix } from "./page-renderer.js";
+/**
+ * Build a {@link PdfChartDrawingSurface} that forwards to the given content
+ * stream. The returned surface is stateful — callers should not mix it with
+ * direct stream mutations for the duration of chart rendering.
+ *
+ * @param stream        Content stream receiving the drawing operators.
+ * @param fontManager   Font manager used for text layout and Type3 fallback.
+ * @param alphaValues   Shared set that accumulates transparency values for
+ *                      later `ExtGState` registration. The surface adds any
+ *                      `color.a` values it observes to this set.
+ */
+export function createChartSurface(stream, fontManager, alphaValues) {
+    const applyAlpha = (color) => {
+        if (color?.a !== undefined && color.a < 1) {
+            alphaValues.add(color.a);
+            stream.setGraphicsState(alphaGsName(color.a));
+        }
+    };
+    const paintFillStroke = (options) => {
+        const { fill, stroke, lineWidth } = options;
+        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) {
+                applyAlpha(stroke);
+            }
+            else if (fillAppliedAlpha) {
+                // Reset to fully opaque for the stroke
+                alphaValues.add(1);
+                stream.setGraphicsState(alphaGsName(1));
+            }
+            if (lineWidth !== undefined) {
+                stream.setLineWidth(lineWidth);
+            }
+        }
+        if (fill && stroke) {
+            stream.fillAndStroke();
+        }
+        else if (fill) {
+            stream.fill();
+        }
+        else if (stroke) {
+            stream.stroke();
+        }
+        else {
+            stream.endPath();
+        }
+    };
+    return {
+        drawRect(options) {
+            const { x, y, width, height, fill, stroke, lineWidth } = options;
+            stream.save();
+            stream.rect(x, y, width, height);
+            paintFillStroke({ fill, stroke, lineWidth });
+            stream.restore();
+            return this;
+        },
+        drawLine(options) {
+            const { x1, y1, x2, y2, color, lineWidth, dashPattern } = options;
+            stream.save();
+            if (color) {
+                stream.setStrokeColor(color);
+                applyAlpha(color);
+            }
+            if (lineWidth !== undefined) {
+                stream.setLineWidth(lineWidth);
+            }
+            if (dashPattern && dashPattern.length > 0) {
+                stream.setDashPattern(dashPattern);
+            }
+            stream.moveTo(x1, y1).lineTo(x2, y2).stroke();
+            stream.restore();
+            return this;
+        },
+        drawText(text, options) {
+            if (!text) {
+                return this;
+            }
+            const fontSize = options.fontSize ?? 10;
+            const color = options.color ?? { r: 0, g: 0, b: 0 };
+            const bold = options.bold ?? false;
+            const italic = options.italic ?? false;
+            const fontFamily = options.fontFamily ?? "Helvetica";
+            const anchor = options.anchor ?? "start";
+            const rotation = options.rotation ?? 0;
+            const resourceName = resolveResourceName(fontManager, fontFamily, bold, italic);
+            const useType3 = fontManager.hasType3Fonts() && !fontManager.hasEmbeddedFont();
+            // Resolve anchor into an x-shift along the text baseline direction.
+            // We measure with the primary resource; mixed-font runs use the
+            // same width estimate, which is correct for Latin-dominant chart
+            // labels and close enough for CJK fallbacks.
+            const measuredWidth = fontManager.measureText(text, resourceName, fontSize);
+            let anchorShift = 0;
+            if (anchor === "middle") {
+                anchorShift = -measuredWidth / 2;
+            }
+            else if (anchor === "end") {
+                anchorShift = -measuredWidth;
+            }
+            stream.save();
+            stream.setFillColor(color);
+            applyAlpha(color);
+            if (rotation === 0) {
+                emitTextWithMatrix(stream, text, 1, 0, 0, 1, options.x + anchorShift, options.y, resourceName, fontSize, fontManager, useType3);
+            }
+            else {
+                // Rotation: chart callers pass degrees clockwise (the interface
+                // is documented that way in `ChartPdfDrawingSurface.drawText`).
+                // PDF's text matrix rotates counter-clockwise with positive
+                // angle, so negate. The 2×3 matrix (a, b, c, d, tx, ty) rotates
+                // around the origin then translates; to rotate around the
+                // anchor point we translate there first (tx, ty) and push the
+                // anchor shift into the local frame (x component).
+                const theta = (-rotation * Math.PI) / 180;
+                const cos = Math.cos(theta);
+                const sin = Math.sin(theta);
+                emitTextWithMatrix(stream, text, cos, sin, -sin, cos, options.x + cos * anchorShift, options.y + sin * anchorShift, resourceName, fontSize, fontManager, useType3);
+            }
+            stream.restore();
+            return this;
+        },
+        drawCircle(options) {
+            const { cx, cy, r, fill, stroke, lineWidth } = options;
+            stream.save();
+            stream.circle(cx, cy, r);
+            paintFillStroke({ 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;
+                }
+            }
+            if (options?.closePath) {
+                stream.closePath();
+            }
+            if (options?.dashPattern && options.dashPattern.length > 0) {
+                stream.setDashPattern(options.dashPattern);
+            }
+            paintFillStroke({
+                fill: options?.fill,
+                stroke: options?.stroke,
+                lineWidth: options?.lineWidth
+            });
+            stream.restore();
+            return this;
+        }
+    };
+}
+function resolveResourceName(fontManager, fontFamily, bold, italic) {
+    if (fontManager.hasEmbeddedFont()) {
+        return fontManager.getEmbeddedResourceName();
+    }
+    return fontManager.ensureFont(resolvePdfFontName(fontFamily, bold, italic));
+}

package/dist/browser/modules/pdf/render/layout-engine.d.ts

@@ -17,12 +17,33 @@
  * - Skip hidden rows and columns
  */
 import type { FontManager } from "../font/font-manager.js";
-import type { PdfSheetData, ResolvedPdfOptions, LayoutPage, LayoutCell, LayoutBorder } from "../types.js";
+import type { PdfSheetData, PdfChartsheetData, ResolvedPdfOptions, LayoutPage, LayoutCell, LayoutBorder } from "../types.js";
 /**
  * Compute the layout for a sheet across one or more PDF pages.
  * Yields to the event loop between each output page.
  */
 export declare function layoutSheet(sheet: PdfSheetData, options: ResolvedPdfOptions, fontManager: FontManager): Promise<LayoutPage[]>;
+/**
+ * Produce the layout for a chartsheet — a single PDF page whose entire
+ * content area is covered by one chart.
+ *
+ * Chartsheets have no row/column grid, so we bypass the cell-layout
+ * pipeline entirely. Page dimensions come from `options.pageSize`, with
+ * orientation overridden by the chartsheet's own `orientation` field
+ * (Excel's chartsheet convention defaults to landscape; see the
+ * `CHARTSHEET_EMU_CX/CY` constants that define the drawing canvas in
+ * `xlsx.browser.ts`).
+ *
+ * The returned LayoutPage has:
+ *  - `cells = []` (no grid to render)
+ *  - `charts` containing one full-content-area chart
+ *  - all other cell-grid arrays empty
+ *
+ * The existing `renderSinglePage` in `pdf-exporter.ts` already handles
+ * pages with zero cells and a non-empty `charts` array via the shared
+ * chart-rendering path, so no exporter changes are needed here.
+ */
+export declare function layoutChartsheet(sheet: PdfChartsheetData, documentOptions: ResolvedPdfOptions): LayoutPage[];
 export declare function paginateRows(rowHeights: number[], availableHeight: number, repeatRowCount: number, rowBreaks: Set<number>): number[][];
 /**
  * Border precedence weight.