@cj-tech-master/excelts 6.2.0 → 7.0.0

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

@@ -0,0 +1,423 @@
+/**
+ * Excel-to-PDF Bridge
+ *
+ * Converts Excel Workbook data into the PDF module's independent data model.
+ * This is the ONLY file in the PDF module that imports from @excel.
+ *
+ * @example
+ * ```typescript
+ * import { Workbook } from "excelts";
+ * import { excelToPdf } from "excelts/pdf";
+ *
+ * const workbook = new Workbook();
+ * // ... build workbook ...
+ * const pdf = excelToPdf(workbook);
+ * ```
+ */
+import { ValueType } from "../excel/enums.js";
+import { formatCellValue } from "../excel/utils/cell-format.js";
+import { base64ToUint8Array } from "../../utils/utils.base.js";
+import { exportPdf } from "./render/pdf-exporter.js";
+import { PdfCellType } from "./types.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Export an Excel Workbook directly to PDF.
+ *
+ * This is a convenience function that converts the Workbook to the PDF module's
+ * data model and then generates the PDF.
+ *
+ * @param workbook - An Excel Workbook instance
+ * @param options  - PDF export options
+ * @returns PDF file as a Uint8Array
+ */
+export function excelToPdf(workbook, options) {
+    const pdfWorkbook = excelWorkbookToPdf(workbook);
+    return exportPdf(pdfWorkbook, options);
+}
+/**
+ * Convert an Excel Workbook to the internal PdfWorkbook data structure.
+ */
+function excelWorkbookToPdf(workbook) {
+    return {
+        title: workbook.title || undefined,
+        creator: workbook.creator || undefined,
+        subject: workbook.subject || undefined,
+        sheets: workbook.worksheets.map(ws => convertSheet(ws, workbook))
+    };
+}
+// =============================================================================
+// Sheet Conversion
+// =============================================================================
+function convertSheet(ws, workbook) {
+    const dimensions = ws.dimensions;
+    const hasData = dimensions && dimensions.model.top > 0 && dimensions.model.left > 0;
+    const bounds = hasData
+        ? {
+            top: dimensions.model.top,
+            left: dimensions.model.left,
+            bottom: dimensions.model.bottom,
+            right: dimensions.model.right
+        }
+        : { top: 0, left: 0, bottom: 0, right: 0 };
+    // Convert columns
+    const columns = new Map();
+    if (hasData) {
+        for (let c = bounds.left; c <= bounds.right; c++) {
+            const col = ws.getColumn(c);
+            columns.set(c, {
+                hidden: col.hidden || undefined,
+                width: col.width ?? undefined
+            });
+        }
+    }
+    // Convert rows
+    const rows = new Map();
+    if (hasData) {
+        for (let r = bounds.top; r <= bounds.bottom; r++) {
+            const row = ws.findRow(r);
+            if (!row) {
+                continue;
+            }
+            const cells = new Map();
+            row.eachCell({ includeEmpty: false }, cell => {
+                cells.set(cell.col, convertCell(cell));
+            });
+            rows.set(r, {
+                hidden: row.hidden || undefined,
+                height: row.height ?? undefined,
+                cells
+            });
+        }
+    }
+    // Convert merges
+    const merges = ws.hasMerges && ws.model.mergeCells ? [...ws.model.mergeCells] : undefined;
+    // Convert pageSetup
+    const ps = ws.pageSetup;
+    const pageSetup = ps
+        ? {
+            orientation: ps.orientation,
+            paperSize: ps.paperSize,
+            margins: ps.margins
+                ? {
+                    left: ps.margins.left,
+                    right: ps.margins.right,
+                    top: ps.margins.top,
+                    bottom: ps.margins.bottom
+                }
+                : undefined,
+            scale: ps.scale,
+            printTitlesRow: ps.printTitlesRow,
+            showGridLines: ps.showGridLines,
+            printArea: ps.printArea
+        }
+        : undefined;
+    // Convert row/col breaks
+    const rowBreaks = ws.rowBreaks?.map((b) => b.id);
+    const colBreaks = ws.colBreaks?.map((b) => b.id);
+    // Convert images
+    const images = collectImages(ws, workbook);
+    // Extend bounds to cover image anchors (so layout engine includes them)
+    if (images) {
+        for (const img of images) {
+            const tl = img.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) {
+                bounds.top = 1;
+                bounds.left = 1;
+            }
+            if (tlCol > bounds.right) {
+                bounds.right = tlCol;
+            }
+            if (tlRow > bounds.bottom) {
+                bounds.bottom = tlRow;
+            }
+            // Also extend to bottom-right anchor if present
+            if (img.range.br) {
+                const br = img.range.br;
+                const brCol = (br.nativeCol ?? br.col ?? 0) + 1;
+                const brRow = (br.nativeRow ?? br.row ?? 0) + 1;
+                if (brCol > bounds.right) {
+                    bounds.right = brCol;
+                }
+                if (brRow > bounds.bottom) {
+                    bounds.bottom = brRow;
+                }
+            }
+        }
+        // Ensure columns/rows exist for extended bounds
+        for (let c = bounds.left; c <= bounds.right; c++) {
+            if (!columns.has(c)) {
+                const col = ws.getColumn(c);
+                columns.set(c, {
+                    hidden: col.hidden || undefined,
+                    width: col.width ?? undefined
+                });
+            }
+        }
+        for (let r = bounds.top; r <= bounds.bottom; r++) {
+            if (!rows.has(r)) {
+                rows.set(r, { cells: new Map() });
+            }
+        }
+    }
+    return {
+        name: ws.name,
+        state: ws.state ?? "visible",
+        bounds,
+        columns,
+        rows,
+        merges,
+        pageSetup,
+        rowBreaks,
+        colBreaks,
+        images
+    };
+}
+// =============================================================================
+// Cell Conversion
+// =============================================================================
+// Use any-typed cell to avoid importing the Cell class directly
+// (Worksheet.eachCell provides it)
+function convertCell(cell) {
+    const type = mapValueType(cell.type);
+    const text = getCellDisplayText(cell);
+    const style = convertCellStyle(cell.style);
+    return {
+        type,
+        value: convertCellValue(cell),
+        text,
+        style,
+        hyperlink: cell.hyperlink || undefined,
+        result: cell.result ?? undefined,
+        col: cell.col
+    };
+}
+function mapValueType(vt) {
+    switch (vt) {
+        case ValueType.Null:
+            return PdfCellType.Empty;
+        case ValueType.Merge:
+            return PdfCellType.Merge;
+        case ValueType.Number:
+            return PdfCellType.Number;
+        case ValueType.String:
+        case ValueType.SharedString:
+            return PdfCellType.String;
+        case ValueType.Date:
+            return PdfCellType.Date;
+        case ValueType.Hyperlink:
+            return PdfCellType.Hyperlink;
+        case ValueType.Formula:
+            return PdfCellType.Formula;
+        case ValueType.RichText:
+            return PdfCellType.RichText;
+        case ValueType.Boolean:
+            return PdfCellType.Boolean;
+        case ValueType.Error:
+            return PdfCellType.Error;
+        default:
+            return PdfCellType.String;
+    }
+}
+/**
+ * Get display text for a cell, applying numFmt formatting.
+ */
+function getCellDisplayText(cell) {
+    if (!cell) {
+        return "";
+    }
+    switch (cell.type) {
+        case ValueType.Null:
+        case ValueType.Merge:
+            return "";
+        case ValueType.RichText:
+        case ValueType.Hyperlink:
+            return cell.text ?? "";
+        case ValueType.Error: {
+            const errValue = cell.value;
+            return errValue?.error ?? cell.text ?? "";
+        }
+        case ValueType.Formula: {
+            const result = cell.result;
+            if (result !== undefined && result !== null) {
+                if (typeof result === "object" && "error" in result) {
+                    return result.error;
+                }
+                return formatCellValueSafe(result, cell.style?.numFmt);
+            }
+            return cell.text ?? "";
+        }
+        default: {
+            const value = cell.value;
+            if (value === null || value === undefined) {
+                return "";
+            }
+            return formatCellValueSafe(value, cell.style?.numFmt);
+        }
+    }
+}
+function formatCellValueSafe(value, numFmt) {
+    const fmt = typeof numFmt === "string" ? numFmt : numFmt?.formatCode;
+    if (fmt && (typeof value === "number" || value instanceof Date || typeof value === "boolean")) {
+        try {
+            return formatCellValue(value, fmt);
+        }
+        catch {
+            // Fall through to default
+        }
+    }
+    if (value instanceof Date) {
+        return value.toLocaleDateString();
+    }
+    return String(value);
+}
+function convertCellValue(cell) {
+    if (cell.type === ValueType.RichText) {
+        // Preserve richText structure for the PDF engine
+        const rtValue = cell.value;
+        if (rtValue?.richText) {
+            return {
+                richText: rtValue.richText.map((run) => ({
+                    text: run.text,
+                    font: run.font ? convertFontStyle(run.font) : undefined
+                }))
+            };
+        }
+    }
+    return cell.value;
+}
+// =============================================================================
+// Style Conversion
+// =============================================================================
+function convertCellStyle(style) {
+    if (!style) {
+        return undefined;
+    }
+    return {
+        font: style.font ? convertFontStyle(style.font) : undefined,
+        numFmt: style.numFmt,
+        fill: style.fill ? convertFill(style.fill) : undefined,
+        border: style.border ? convertBorders(style.border) : undefined,
+        alignment: style.alignment ? convertAlignment(style.alignment) : undefined
+    };
+}
+function convertFontStyle(font) {
+    return {
+        name: font.name,
+        size: font.size,
+        bold: font.bold,
+        italic: font.italic,
+        strike: font.strike,
+        underline: font.underline,
+        color: font.color ? convertColor(font.color) : undefined
+    };
+}
+function convertColor(color) {
+    return {
+        argb: color.argb,
+        theme: color.theme,
+        tint: color.tint
+    };
+}
+function convertFill(fill) {
+    const result = {
+        type: fill.type ?? "pattern",
+        pattern: fill.pattern,
+        fgColor: fill.fgColor ? convertColor(fill.fgColor) : undefined
+    };
+    if (fill.stops) {
+        result.stops = fill.stops.map((s) => ({
+            color: convertColor(s.color)
+        }));
+    }
+    return result;
+}
+function convertBorderSide(border) {
+    return {
+        style: border.style,
+        color: border.color ? convertColor(border.color) : undefined
+    };
+}
+function convertBorders(borders) {
+    return {
+        top: borders.top ? convertBorderSide(borders.top) : undefined,
+        right: borders.right ? convertBorderSide(borders.right) : undefined,
+        bottom: borders.bottom ? convertBorderSide(borders.bottom) : undefined,
+        left: borders.left ? convertBorderSide(borders.left) : undefined
+    };
+}
+function convertAlignment(alignment) {
+    return {
+        horizontal: alignment.horizontal,
+        vertical: alignment.vertical,
+        wrapText: alignment.wrapText,
+        indent: alignment.indent,
+        textRotation: alignment.textRotation
+    };
+}
+// =============================================================================
+// Image Collection
+// =============================================================================
+function collectImages(ws, workbook) {
+    const wsImages = ws.getImages?.();
+    if (!wsImages || !Array.isArray(wsImages) || wsImages.length === 0) {
+        return undefined;
+    }
+    const images = [];
+    for (const wsImage of wsImages) {
+        if (!wsImage.range?.tl) {
+            continue;
+        }
+        const imageId = wsImage.imageId;
+        const mediaItem = workbook.getImage?.(Number(imageId));
+        if (!mediaItem) {
+            continue;
+        }
+        // Get image data
+        let data;
+        if (mediaItem.buffer instanceof Uint8Array) {
+            data = mediaItem.buffer;
+        }
+        else if (mediaItem.base64) {
+            data = base64ToUint8Array(mediaItem.base64);
+        }
+        if (!data || data.length === 0) {
+            continue;
+        }
+        const format = mediaItem.extension;
+        if (format !== "jpeg" && format !== "png") {
+            continue;
+        }
+        images.push({
+            data,
+            format: format,
+            range: {
+                tl: {
+                    col: wsImage.range.tl.col ?? 0,
+                    row: wsImage.range.tl.row ?? 0,
+                    nativeCol: wsImage.range.tl.nativeCol,
+                    nativeRow: wsImage.range.tl.nativeRow,
+                    nativeColOff: wsImage.range.tl.nativeColOff,
+                    nativeRowOff: wsImage.range.tl.nativeRowOff
+                },
+                br: wsImage.range.br
+                    ? {
+                        col: wsImage.range.br.col ?? 0,
+                        row: wsImage.range.br.row ?? 0,
+                        nativeCol: wsImage.range.br.nativeCol,
+                        nativeRow: wsImage.range.br.nativeRow,
+                        nativeColOff: wsImage.range.br.nativeColOff,
+                        nativeRowOff: wsImage.range.br.nativeRowOff
+                    }
+                    : undefined,
+                ext: wsImage.range.ext
+                    ? { width: wsImage.range.ext.width, height: wsImage.range.ext.height }
+                    : undefined
+            }
+        });
+    }
+    return images.length > 0 ? images : undefined;
+}

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

@@ -1,39 +1,37 @@
 /**
  * PDF module for excelts.
  *
- * Provides Excel-to-PDF conversion with zero external dependencies.
- * Supports cell values, fonts, colors, borders, fills, alignment,
- * merged cells, pagination, and customizable page layout.
+ * A full-featured, zero-dependency PDF engine.
  *
- * @example
+ * @example Standalone:
  * ```typescript
- * import { Workbook, PdfExporter } from "excelts";
+ * import { pdf } from "excelts/pdf";
  *
- * const workbook = new Workbook();
- * const sheet = workbook.addWorksheet("Sales");
- * sheet.columns = [
- *   { header: "Product", key: "product", width: 20 },
- *   { header: "Revenue", key: "revenue", width: 15 }
- * ];
- * sheet.addRow({ product: "Widget", revenue: 1000 });
+ * const bytes = pdf([
+ *   ["Product", "Revenue"],
+ *   ["Widget", 1000],
+ *   ["Gadget", 2500]
+ * ]);
+ * ```
  *
- * const exporter = new PdfExporter(workbook);
- * const pdfBuffer = exporter.export({
- *   pageSize: "A4",
- *   orientation: "portrait",
- *   fitToPage: true,
- *   showGridLines: true,
- *   showPageNumbers: true
- * });
+ * @example From Excel Workbook:
+ * ```typescript
+ * import { Workbook } from "excelts";
+ * import { excelToPdf } from "excelts/pdf";
  *
- * // Write to file (Node.js)
- * import { writeFileSync } from "fs";
- * writeFileSync("output.pdf", pdfBuffer);
+ * const workbook = new Workbook();
+ * const sheet = workbook.addWorksheet("Sales");
+ * sheet.addRow(["Product", "Revenue"]);
+ * const bytes = excelToPdf(workbook);
  * ```
  *
  * @module pdf
  */
-export { PdfExporter, exportPdf } from "./render/pdf-exporter.js";
+/** 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 type { PdfCell, PdfRow, PdfColumn, PdfSheet, PdfBook, PdfImage } from "./pdf.js";
 export type { PdfExportOptions, PdfOrientation, PdfPageSize, PdfMargins, PdfColor, PageSizeName } from "./types.js";
 export { PageSizes } from "./types.js";
 export { PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./errors.js";

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

@@ -1,42 +1,39 @@
 /**
  * PDF module for excelts.
  *
- * Provides Excel-to-PDF conversion with zero external dependencies.
- * Supports cell values, fonts, colors, borders, fills, alignment,
- * merged cells, pagination, and customizable page layout.
+ * A full-featured, zero-dependency PDF engine.
  *
- * @example
+ * @example Standalone:
  * ```typescript
- * import { Workbook, PdfExporter } from "excelts";
+ * import { pdf } from "excelts/pdf";
  *
- * const workbook = new Workbook();
- * const sheet = workbook.addWorksheet("Sales");
- * sheet.columns = [
- *   { header: "Product", key: "product", width: 20 },
- *   { header: "Revenue", key: "revenue", width: 15 }
- * ];
- * sheet.addRow({ product: "Widget", revenue: 1000 });
+ * const bytes = pdf([
+ *   ["Product", "Revenue"],
+ *   ["Widget", 1000],
+ *   ["Gadget", 2500]
+ * ]);
+ * ```
  *
- * const exporter = new PdfExporter(workbook);
- * const pdfBuffer = exporter.export({
- *   pageSize: "A4",
- *   orientation: "portrait",
- *   fitToPage: true,
- *   showGridLines: true,
- *   showPageNumbers: true
- * });
+ * @example From Excel Workbook:
+ * ```typescript
+ * import { Workbook } from "excelts";
+ * import { excelToPdf } from "excelts/pdf";
  *
- * // Write to file (Node.js)
- * import { writeFileSync } from "fs";
- * writeFileSync("output.pdf", pdfBuffer);
+ * const workbook = new Workbook();
+ * const sheet = workbook.addWorksheet("Sales");
+ * sheet.addRow(["Product", "Revenue"]);
+ * const bytes = excelToPdf(workbook);
  * ```
  *
  * @module pdf
  */
 // =============================================================================
-// Core Export
+// Public API
 // =============================================================================
-export { PdfExporter, exportPdf } from "./render/pdf-exporter.js";
+/** 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 { PageSizes } from "./types.js";
 // =============================================================================
 // Errors

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

@@ -0,0 +1,121 @@
+/**
+ * Simplified PDF generation API.
+ *
+ * Provides a concise way to create PDFs from plain data — no need to manually
+ * construct Map objects, compute bounds, or specify cell types.
+ *
+ * @example Simplest — pass a 2D array:
+ * ```typescript
+ * import { pdf } from "@cj-tech-master/excelts/pdf";
+ *
+ * const bytes = pdf([
+ *   ["Product", "Revenue"],
+ *   ["Widget", 1000],
+ *   ["Gadget", 2500]
+ * ]);
+ * ```
+ *
+ * @example With options:
+ * ```typescript
+ * const bytes = pdf([
+ *   ["Name", "Score"],
+ *   ["Alice", 95],
+ *   ["Bob", 87]
+ * ], { showGridLines: true, title: "Scores" });
+ * ```
+ *
+ * @example Multiple sheets:
+ * ```typescript
+ * const bytes = pdf({
+ *   sheets: [
+ *     { name: "Sales", data: [["Product", "Revenue"], ["Widget", 1000]] },
+ *     { name: "Costs", data: [["Item", "Amount"], ["Rent", 500]] }
+ *   ]
+ * });
+ * ```
+ *
+ * @example With column widths and styles:
+ * ```typescript
+ * const bytes = pdf({
+ *   name: "Report",
+ *   columns: [{ width: 25 }, { width: 15 }],
+ *   data: [
+ *     ["Product", "Revenue"],
+ *     ["Widget", "$1,000"]
+ *   ]
+ * });
+ * ```
+ */
+import { type PdfExportOptions } from "./types.js";
+/** A cell value: string, number, boolean, Date, null, or a styled cell object. */
+export type PdfCellValue = string | number | boolean | Date | null | undefined | PdfCell;
+/** A cell with an explicit value and optional style overrides. */
+export interface PdfCell {
+    value: string | number | boolean | Date | null | undefined;
+    bold?: boolean;
+    italic?: boolean;
+    fontSize?: number;
+    fontColor?: string;
+    fillColor?: string;
+    align?: "left" | "center" | "right";
+}
+/** A row is an array of cell values. */
+export type PdfRow = PdfCellValue[];
+/** Column configuration. */
+export interface PdfColumn {
+    width?: number;
+    header?: string;
+}
+/** An image to embed in a sheet. */
+export interface PdfImage {
+    /** Raw image bytes (JPEG or PNG). */
+    data: Uint8Array;
+    /** Image format. */
+    format: "jpeg" | "png";
+    /**
+     * Top-left column position (0-indexed).
+     * This is relative to the final sheet grid — if column headers are used,
+     * they occupy the first row, so data starts at row 1.
+     */
+    col: number;
+    /**
+     * Top-left row position (0-indexed).
+     * This is relative to the final sheet grid — if column headers are used,
+     * row 0 is the header row, and data rows start at row 1.
+     */
+    row: number;
+    /** Image width in pixels. */
+    width: number;
+    /** Image height in pixels. */
+    height: number;
+}
+/** A single sheet definition. */
+export interface PdfSheet {
+    name?: string;
+    columns?: (PdfColumn | number)[];
+    data: PdfRow[];
+    images?: PdfImage[];
+}
+/** A multi-sheet document definition. */
+export interface PdfBook {
+    title?: string;
+    author?: string;
+    sheets: PdfSheet[];
+}
+/**
+ * The input to {@link pdf} — can be:
+ * - A 2D array (single sheet)
+ * - A sheet object `{ name?, columns?, data, images? }`
+ * - A workbook object `{ sheets: [...] }`
+ */
+export type PdfInput = PdfRow[] | PdfSheet | PdfBook;
+/**
+ * Generate a PDF.
+ *
+ * Accepts anything from a plain 2D array to a multi-sheet workbook.
+ *
+ * @param input   - 2D array, sheet object, or workbook object
+ * @param options - PDF export options (page size, margins, etc.)
+ * @returns PDF file as Uint8Array
+ */
+export declare function pdf(input: PdfInput, options?: PdfExportOptions): Uint8Array;