@cj-tech-master/excelts 9.4.2 → 9.5.0

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

@@ -124,37 +124,169 @@ export interface PdfPageSetupData {
     showGridLines?: boolean;
     printArea?: string;
 }
+/** Anchor range shared by embedded images and charts. */
+export interface PdfAnchorRange {
+    tl: {
+        col: number;
+        row: number;
+        nativeCol?: number;
+        nativeRow?: number;
+        nativeColOff?: number;
+        nativeRowOff?: number;
+    };
+    br?: {
+        col: number;
+        row: number;
+        nativeCol?: number;
+        nativeRow?: number;
+        nativeColOff?: number;
+        nativeRowOff?: number;
+    };
+    /**
+     * Image variant uses pixels (px × 0.75 = pt).
+     * Chart variant uses EMU (cx / 9525 = pt).
+     * The layout engine picks the correct conversion via `extUnit`.
+     */
+    ext?: {
+        width: number;
+        height: number;
+    };
+    /** Unit of measure for `ext`. Defaults to "px" for backwards compatibility. */
+    extUnit?: "px" | "emu";
+}
 /** An image embedded in a sheet. */
 export interface PdfSheetImage {
     data: Uint8Array;
     format: "jpeg" | "png";
-    range: {
-        tl: {
-            col: number;
-            row: number;
-            nativeCol?: number;
-            nativeRow?: number;
-            nativeColOff?: number;
-            nativeRowOff?: number;
-        };
-        br?: {
-            col: number;
-            row: number;
-            nativeCol?: number;
-            nativeRow?: number;
-            nativeColOff?: number;
-            nativeRowOff?: number;
-        };
-        ext?: {
-            width: number;
-            height: number;
-        };
+    range: PdfAnchorRange;
+}
+/**
+ * Path operator set understood by {@link PdfChartDrawingSurface}.`drawPath`.
+ * Structurally compatible with `ChartPdfPathOp` from `@excel/chart` so the
+ * excel-bridge can forward between the two at the cast boundary.
+ */
+export type PdfChartPathOp = {
+    op: "move";
+    x: number;
+    y: number;
+} | {
+    op: "line";
+    x: number;
+    y: number;
+} | {
+    op: "curve";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    x3: number;
+    y3: number;
+} | {
+    op: "close";
+};
+/**
+ * Drawing surface used by vector chart renderers when embedded in a PDF page.
+ *
+ * Structurally compatible with `ChartPdfDrawingSurface` from the Excel chart
+ * renderer. Declared locally in the PDF layer so the rendering pipeline does
+ * not need to import chart types — only `excel-bridge.ts` (the documented
+ * layer-crossing file) forwards real chart models to the surface.
+ *
+ * All coordinates are in **PDF points with bottom-left origin**, matching the
+ * convention the chart renderer emits after its internal Y-flip.
+ */
+export interface PdfChartDrawingSurface {
+    drawRect(options: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        fill?: PdfColor;
+        stroke?: PdfColor;
+        lineWidth?: number;
+    }): unknown;
+    drawLine(options: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+        color?: PdfColor;
+        lineWidth?: number;
+        dashPattern?: number[];
+    }): unknown;
+    drawText(text: string, options: {
+        x: number;
+        y: number;
+        fontSize?: number;
+        color?: PdfColor;
+        rotation?: number;
+        anchor?: "start" | "middle" | "end";
+        bold?: boolean;
+        italic?: boolean;
+        fontFamily?: string;
+    }): unknown;
+    drawCircle?(options: {
+        cx: number;
+        cy: number;
+        r: number;
+        fill?: PdfColor;
+        stroke?: PdfColor;
+        lineWidth?: number;
+    }): unknown;
+    drawPath?(ops: PdfChartPathOp[], options?: {
+        fill?: PdfColor;
+        stroke?: PdfColor;
+        closePath?: boolean;
+        lineWidth?: number;
+        dashPattern?: number[];
+    }): unknown;
+}
+/**
+ * A chart embedded in a sheet.
+ *
+ * Either provides a `drawVector` callback (preferred — selectable text,
+ * resolution-independent shapes) or a pre-rasterised `raster` payload that
+ * falls through to the image XObject pipeline. Exactly one of the two should
+ * be populated; if both are present the renderer prefers `drawVector`.
+ */
+export interface PdfSheetChart {
+    range: PdfAnchorRange;
+    /**
+     * Vector renderer. Bound in `excel-bridge.ts` over the concrete chart
+     * model; the PDF pipeline invokes it with a surface that adapts the
+     * current page's content stream. `rect` is in PDF page coordinates
+     * (bottom-left origin).
+     */
+    drawVector?: (surface: PdfChartDrawingSurface, rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => void;
+    /**
+     * Raster fallback used when the chart has no vector path (currently only
+     * ChartEx layouts not in the `VECTOR_PDF_CHART_EX_LAYOUT_IDS` whitelist).
+     */
+    raster?: {
+        data: Uint8Array;
+        format: "png" | "jpeg";
     };
 }
-/** A single sheet in the PDF input model. */
+/** A single cell-grid sheet in the PDF input model. */
 export interface PdfSheetData {
+    /**
+     * Discriminator. Optional for backwards compatibility — when absent the
+     * exporter treats the sheet as a regular cell-grid worksheet.
+     */
+    kind?: "worksheet";
     name: string;
     state?: "visible" | "hidden" | "veryHidden";
+    /**
+     * Tab order from the source workbook. Used by `excelToPdf` to interleave
+     * worksheets and chartsheets in the same order Excel would display them.
+     * Optional; when absent the sheet keeps its array position.
+     */
+    orderNo?: number;
     /** Data bounds (1-based) */
     bounds: {
         top: number;
@@ -175,7 +307,54 @@ export interface PdfSheetData {
     colBreaks?: number[];
     /** Embedded images */
     images?: PdfSheetImage[];
+    /** Embedded charts (classic + ChartEx) */
+    charts?: PdfSheetChart[];
 }
+/**
+ * A chartsheet — a single-chart "sheet" with no cell grid.
+ *
+ * Excel stores chartsheets under `xl/chartsheets/sheetN.xml`, parallel to
+ * the worksheet family. A chartsheet has no rows/columns/cells; the entire
+ * printed canvas is one chart. The PDF pipeline honours that semantic: a
+ * chartsheet produces exactly one LayoutPage with a single chart filling
+ * the content area (below the optional header, above the optional footer).
+ */
+export interface PdfChartsheetData {
+    kind: "chartsheet";
+    name: string;
+    state?: "visible" | "hidden" | "veryHidden";
+    /** Tab order — used to interleave with worksheets. See {@link PdfSheetData.orderNo}. */
+    orderNo?: number;
+    /**
+     * Page orientation override. Excel's chartsheets default to landscape
+     * (wider canvas suits most charts) and we keep that default when this
+     * field is absent.
+     */
+    orientation?: "portrait" | "landscape";
+    /** The single chart that fills the sheet canvas. */
+    chart: {
+        drawVector?: PdfSheetChart["drawVector"];
+        raster?: PdfSheetChart["raster"];
+    };
+    /**
+     * Optional page setup overrides. Only a subset of the worksheet
+     * `PdfPageSetupData` is meaningful here (chartsheets don't have
+     * gridlines, print titles, row/col breaks, etc.). The renderer reads
+     * `orientation` off `this.orientation` first, then falls back to
+     * `pageSetup?.orientation`.
+     */
+    pageSetup?: PdfPageSetupData;
+}
+/**
+ * Union of sheet shapes accepted by {@link PdfWorkbook.sheets}.
+ *
+ * Named `PdfWorkbookSheet` (not `PdfSheet`) because `PdfSheet` already
+ * denotes a different user-facing input type in `pdf.ts` — the simple
+ * "pass me a 2D array or a single sheet description" shape.
+ */
+export type PdfWorkbookSheet = PdfSheetData | PdfChartsheetData;
+/** Type guard distinguishing chartsheets from cell-grid worksheets. */
+export declare function isPdfChartsheet(sheet: PdfWorkbookSheet): sheet is PdfChartsheetData;
 /**
  * A workbook data structure for PDF generation.
  * This is a plain data object — not tied to the Excel module.
@@ -184,7 +363,7 @@ export interface PdfWorkbook {
     title?: string;
     creator?: string;
     subject?: string;
-    sheets: PdfSheetData[];
+    sheets: PdfWorkbookSheet[];
 }
 /**
  * Standard page sizes in PDF points (1 point = 1/72 inch).
@@ -750,6 +929,8 @@ export interface LayoutPage {
     rowHeights: number[];
     /** Images to render on this page */
     images: LayoutImage[];
+    /** Charts to render on this page */
+    charts: LayoutChart[];
     /** Scale factor applied to this page (for fitToPage) */
     scaleFactor: number;
 }
@@ -764,3 +945,26 @@ export interface LayoutImage {
     /** Rectangle in page coordinates (PDF points, origin bottom-left) */
     rect: PdfRect;
 }
+/**
+ * A positioned chart on a PDF page.
+ *
+ * Either `drawVector` (preferred) or `raster` must be provided; the exporter
+ * prefers `drawVector` when both are present so the PDF keeps selectable
+ * text and resolution-independent shapes.
+ */
+export interface LayoutChart {
+    /** Rectangle in page coordinates (PDF points, origin bottom-left) */
+    rect: PdfRect;
+    /** Vector rendering callback, if the chart can be drawn as PDF geometry. */
+    drawVector?: (surface: PdfChartDrawingSurface, rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => void;
+    /** Raster fallback for charts that have no vector path. */
+    raster?: {
+        data: Uint8Array;
+        format: "png" | "jpeg";
+    };
+}

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

@@ -23,6 +23,10 @@ export const PdfCellType = {
     Hyperlink: 8,
     Merge: 9
 };
+/** Type guard distinguishing chartsheets from cell-grid worksheets. */
+export function isPdfChartsheet(sheet) {
+    return sheet.kind === "chartsheet";
+}
 /**
  * Predefined page sizes.
  */

package/dist/browser/modules/pdf/word-bridge.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Word-to-PDF Bridge
+ *
+ * Converts a Word document (DocxDocument) to PDF.
+ * Like excel-bridge.ts, this is the ONLY file in the PDF module that imports
+ * from @word.
+ *
+ * @example
+ * ```typescript
+ * import { readDocx } from "excelts/word";
+ * import { docxToPdf } from "excelts/pdf";
+ *
+ * const doc = await readDocx(docxBytes);
+ * const pdfBytes = await docxToPdf(doc);
+ * ```
+ *
+ * Note: This is a simple flow-based renderer. For high-fidelity output,
+ * consider using Microsoft Word or LibreOffice.
+ */
+import type { DocxDocument } from "../word/types.js";
+/** Options for DOCX → PDF conversion. */
+export interface DocxToPdfOptions {
+    /** Page width in points (default: from document sectPr or 612 US Letter). */
+    readonly pageWidth?: number;
+    /** Page height in points (default: from document sectPr or 792 US Letter). */
+    readonly pageHeight?: number;
+    /** Top margin in points (default: from sectPr or 72). */
+    readonly marginTop?: number;
+    /** Bottom margin in points (default: from sectPr or 72). */
+    readonly marginBottom?: number;
+    /** Left margin in points (default: from sectPr or 72). */
+    readonly marginLeft?: number;
+    /** Right margin in points (default: from sectPr or 72). */
+    readonly marginRight?: number;
+    /** Default font family (default: "Times-Roman"). */
+    readonly defaultFont?: string;
+    /** Default font size in points (default: 11). */
+    readonly defaultFontSize?: number;
+}
+/**
+ * Convert a DocxDocument to PDF bytes.
+ *
+ * @param doc - The DOCX document model (from readDocx or DocumentBuilder.build()).
+ * @param options - PDF rendering options.
+ * @returns Promise of PDF bytes.
+ */
+export declare function docxToPdf(doc: DocxDocument, options?: DocxToPdfOptions): Promise<Uint8Array>;

package/dist/browser/modules/pdf/word-bridge.js

@@ -0,0 +1,304 @@
+/**
+ * Word-to-PDF Bridge
+ *
+ * Converts a Word document (DocxDocument) to PDF.
+ * Like excel-bridge.ts, this is the ONLY file in the PDF module that imports
+ * from @word.
+ *
+ * @example
+ * ```typescript
+ * import { readDocx } from "excelts/word";
+ * import { docxToPdf } from "excelts/pdf";
+ *
+ * const doc = await readDocx(docxBytes);
+ * const pdfBytes = await docxToPdf(doc);
+ * ```
+ *
+ * Note: This is a simple flow-based renderer. For high-fidelity output,
+ * consider using Microsoft Word or LibreOffice.
+ */
+import { PdfDocumentBuilder } from "./builder/document-builder.js";
+/**
+ * Convert a DocxDocument to PDF bytes.
+ *
+ * @param doc - The DOCX document model (from readDocx or DocumentBuilder.build()).
+ * @param options - PDF rendering options.
+ * @returns Promise of PDF bytes.
+ */
+export async function docxToPdf(doc, options) {
+    const opts = {
+        pageWidth: options?.pageWidth ?? 612,
+        pageHeight: options?.pageHeight ?? 792,
+        marginTop: options?.marginTop ?? 72,
+        marginBottom: options?.marginBottom ?? 72,
+        marginLeft: options?.marginLeft ?? 72,
+        marginRight: options?.marginRight ?? 72,
+        defaultFont: options?.defaultFont ?? "Times-Roman",
+        defaultFontSize: options?.defaultFontSize ?? 11
+    };
+    // Use section properties if available
+    const sectProps = doc.sectionProperties;
+    if (sectProps?.pageSize && !options?.pageWidth) {
+        opts.pageWidth = twipsToPt(sectProps.pageSize.width);
+        opts.pageHeight = twipsToPt(sectProps.pageSize.height);
+        if (sectProps.pageSize.orientation === "landscape") {
+            [opts.pageWidth, opts.pageHeight] = [opts.pageHeight, opts.pageWidth];
+        }
+    }
+    if (sectProps?.margins && !options?.marginTop) {
+        opts.marginTop = twipsToPt(sectProps.margins.top);
+        opts.marginBottom = twipsToPt(sectProps.margins.bottom);
+        opts.marginLeft = twipsToPt(sectProps.margins.left);
+        opts.marginRight = twipsToPt(sectProps.margins.right);
+    }
+    const builder = new PdfDocumentBuilder();
+    if (doc.coreProperties?.title || doc.coreProperties?.creator) {
+        builder.setMetadata({
+            title: doc.coreProperties?.title,
+            author: doc.coreProperties?.creator,
+            subject: doc.coreProperties?.subject
+        });
+    }
+    const state = {
+        builder,
+        opts,
+        doc,
+        rIdToImage: buildImageMap(doc),
+        currentPage: null,
+        cursorY: 0,
+        currentPageIndex: 0
+    };
+    newPage(state);
+    for (const item of doc.body) {
+        renderBodyContent(state, item);
+    }
+    return builder.build();
+}
+function newPage(state) {
+    state.currentPage = state.builder.addPage({
+        width: state.opts.pageWidth,
+        height: state.opts.pageHeight
+    });
+    state.cursorY = state.opts.pageHeight - state.opts.marginTop;
+    state.currentPageIndex++;
+}
+function ensureSpace(state, needed) {
+    if (state.cursorY - needed < state.opts.marginBottom) {
+        newPage(state);
+    }
+}
+function renderBodyContent(state, item) {
+    if (!("type" in item)) {
+        return;
+    }
+    switch (item.type) {
+        case "paragraph":
+            renderParagraphPdf(state, item);
+            break;
+        case "table":
+            renderTablePdf(state, item);
+            break;
+        case "math":
+            renderTextAtCursor(state, "[equation]", { italic: true });
+            break;
+        case "chart":
+            renderTextAtCursor(state, `[${item.chart.type} chart]`, { italic: true });
+            break;
+        default:
+            break;
+    }
+}
+function renderParagraphPdf(state, para) {
+    const props = para.properties;
+    const spacing = props?.spacing;
+    if (spacing?.before) {
+        state.cursorY -= twipsToPt(spacing.before);
+    }
+    const text = collectText(para);
+    if (!text.trim()) {
+        state.cursorY -= state.opts.defaultFontSize * 1.2;
+        return;
+    }
+    // Determine font size and weight based on style
+    let fontSize = state.opts.defaultFontSize;
+    let bold = false;
+    const styleId = props?.style?.toLowerCase() ?? "";
+    if (styleId === "heading1" || styleId === "title") {
+        fontSize = 24;
+        bold = true;
+    }
+    else if (styleId === "heading2") {
+        fontSize = 18;
+        bold = true;
+    }
+    else if (styleId === "heading3") {
+        fontSize = 14;
+        bold = true;
+    }
+    else if (styleId === "heading4") {
+        fontSize = 12;
+        bold = true;
+    }
+    let leftIndent = 0;
+    if (props?.indent?.left !== undefined) {
+        leftIndent = twipsToPt(props.indent.left);
+    }
+    const x = state.opts.marginLeft + leftIndent;
+    const availableWidth = state.opts.pageWidth - state.opts.marginLeft - state.opts.marginRight - leftIndent;
+    const lineHeight = fontSize * 1.2;
+    const estimatedLines = Math.max(1, Math.ceil((text.length * fontSize * 0.5) / availableWidth));
+    ensureSpace(state, estimatedLines * lineHeight);
+    // Simple approach: render entire paragraph as one text block
+    state.currentPage.drawText(text, {
+        x,
+        y: state.cursorY - fontSize,
+        fontSize,
+        bold,
+        maxWidth: availableWidth,
+        lineHeight: 1.2
+    });
+    state.cursorY -= estimatedLines * lineHeight;
+    if (spacing?.after) {
+        state.cursorY -= twipsToPt(spacing.after);
+    }
+    else {
+        state.cursorY -= 6;
+    }
+}
+function collectText(para) {
+    let text = "";
+    for (const child of para.children) {
+        const run = childToRun(child);
+        if (run) {
+            text += runToText(run);
+        }
+    }
+    return text;
+}
+function childToRun(child) {
+    if ("content" in child && !("type" in child)) {
+        return child;
+    }
+    if ("type" in child) {
+        const typed = child;
+        if (typed.type === "hyperlink" && typed.children) {
+            for (const c of typed.children) {
+                if ("content" in c && !("type" in c)) {
+                    return c;
+                }
+            }
+        }
+        else if (typed.type === "insertedRun" ||
+            typed.type === "deletedRun" ||
+            typed.type === "movedFromRun" ||
+            typed.type === "movedToRun") {
+            return typed.run;
+        }
+    }
+    return undefined;
+}
+function runToText(run) {
+    let text = "";
+    for (const c of run.content) {
+        switch (c.type) {
+            case "text":
+                text += c.text;
+                break;
+            case "tab":
+                text += "\t";
+                break;
+            case "break":
+            case "carriageReturn":
+                text += "\n";
+                break;
+            case "noBreakHyphen":
+                text += "\u2011";
+                break;
+            case "symbol":
+                try {
+                    text += String.fromCodePoint(parseInt(c.char, 16));
+                }
+                catch {
+                    // Invalid symbol code - skip
+                }
+                break;
+            case "field":
+                if (c.cachedValue) {
+                    text += c.cachedValue;
+                }
+                break;
+        }
+    }
+    return text;
+}
+function renderTablePdf(state, table) {
+    const pageWidth = state.opts.pageWidth - state.opts.marginLeft - state.opts.marginRight;
+    const numCols = Math.max(...table.rows.map(r => r.cells.length));
+    const defaultColWidth = pageWidth / numCols;
+    const rowHeight = 20;
+    for (const row of table.rows) {
+        ensureSpace(state, rowHeight);
+        let x = state.opts.marginLeft;
+        const rowTop = state.cursorY;
+        const rowBottom = state.cursorY - rowHeight;
+        for (const cell of row.cells) {
+            const span = cell.properties?.gridSpan ?? 1;
+            const cellWidth = defaultColWidth * span;
+            state.currentPage.drawRect({
+                x,
+                y: rowBottom,
+                width: cellWidth,
+                height: rowHeight,
+                stroke: { r: 0, g: 0, b: 0 },
+                lineWidth: 0.5
+            });
+            const cellText = getCellText(cell);
+            if (cellText) {
+                state.currentPage.drawText(cellText, {
+                    x: x + 4,
+                    y: rowTop - 14,
+                    fontSize: 10,
+                    maxWidth: cellWidth - 8
+                });
+            }
+            x += cellWidth;
+        }
+        state.cursorY = rowBottom;
+    }
+    state.cursorY -= 6;
+}
+function getCellText(cell) {
+    let text = "";
+    for (const item of cell.content) {
+        if ("type" in item && item.type === "paragraph") {
+            text += collectText(item) + " ";
+        }
+    }
+    return text.trim();
+}
+function twipsToPt(twips) {
+    return twips / 20;
+}
+function renderTextAtCursor(state, text, opts) {
+    const fontSize = opts?.fontSize ?? state.opts.defaultFontSize;
+    ensureSpace(state, fontSize * 1.2);
+    state.currentPage.drawText(text, {
+        x: state.opts.marginLeft,
+        y: state.cursorY - fontSize,
+        fontSize,
+        bold: opts?.bold,
+        italic: opts?.italic
+    });
+    state.cursorY -= fontSize * 1.2;
+}
+function buildImageMap(doc) {
+    const map = new Map();
+    if (doc.images) {
+        for (const img of doc.images) {
+            if (img.rId) {
+                map.set(img.rId, img);
+            }
+        }
+    }
+    return map;
+}