@cj-tech-master/excelts 6.2.0 → 7.0.0

package/dist/cjs/modules/pdf/render/pdf-exporter.js

@@ -1,23 +1,14 @@
 "use strict";
 /**
- * PDF Exporter - Main orchestrator for Excel-to-PDF conversion.
+ * PDF Exporter - Main orchestrator for PDF document generation.
  *
  * Coordinates the layout engine, page renderer, font manager, and PDF writer
- * to produce a complete PDF document from an Excel workbook.
+ * to produce a complete PDF document from a PdfWorkbook data structure.
  *
- * @example
- * ```typescript
- * import { Workbook, PdfExporter } from "excelts";
- *
- * const workbook = new Workbook();
- * // ... populate workbook ...
- *
- * const exporter = new PdfExporter(workbook);
- * const pdfBuffer = exporter.export({ fitToPage: true });
- * ```
+ * This module is fully independent of the Excel module.
+ * It is used internally by the public `pdf()` and `excelToPdf()` APIs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PdfExporter = void 0;
 exports.exportPdf = exportPdf;
 const pdf_writer_1 = require("../core/pdf-writer");
 const pdf_object_1 = require("../core/pdf-object");
@@ -34,22 +25,17 @@ const style_converter_1 = require("./style-converter");
 // Public API
 // =============================================================================
 /**
- * Export a workbook to PDF format.
+ * Export a PdfWorkbook to PDF format.
  *
- * @param workbook - The workbook to export
+ * @param workbook - The workbook data to export
  * @param options - Export options controlling layout, pagination, and appearance
  * @returns PDF file as a Uint8Array
- * @throws {PdfError} If the workbook has no worksheets or export fails
- *
- * @example
- * ```typescript
- * const pdf = exportPdf(workbook, { fitToPage: true, showGridLines: true });
- * ```
+ * @throws {PdfError} If the workbook has no sheets or export fails
  */
 function exportPdf(workbook, options) {
-    const worksheets = selectWorksheets(workbook, options?.sheets);
-    if (worksheets.length === 0) {
-        throw new errors_1.PdfError("No worksheets to export. The workbook is empty or no sheets matched.");
+    const sheets = selectSheets(workbook, options?.sheets);
+    if (sheets.length === 0) {
+        throw new errors_1.PdfError("No sheets to export. The workbook is empty or no sheets matched.");
     }
     const fontManager = new font_manager_1.FontManager();
     const writer = new pdf_writer_1.PdfWriter();
@@ -63,19 +49,19 @@ function exportPdf(workbook, options) {
             throw new errors_1.PdfRenderError("Failed to parse TrueType font", { cause: err });
         }
     }
-    // --- Step 1: Layout all worksheets ---
+    // --- Step 1: Layout all sheets ---
     const allPages = [];
-    for (const worksheet of worksheets) {
+    for (const sheet of sheets) {
         try {
-            const resolved = resolveOptions(options, worksheet);
-            const pages = (0, layout_engine_1.layoutWorksheet)(worksheet, resolved, fontManager);
+            const resolved = resolveOptions(options, sheet);
+            const pages = (0, layout_engine_1.layoutSheet)(sheet, resolved, fontManager);
             allPages.push(...pages);
         }
         catch (err) {
-            throw new errors_1.PdfRenderError(`Failed to layout worksheet "${worksheet.name}"`, { cause: err });
+            throw new errors_1.PdfRenderError(`Failed to layout sheet "${sheet.name}"`, { cause: err });
         }
     }
-    const documentOptions = resolveOptions(options, worksheets[0]);
+    const documentOptions = resolveOptions(options, sheets[0]);
     if (allPages.length === 0) {
         // Create at least one empty page
         allPages.push({
@@ -84,17 +70,17 @@ function exportPdf(workbook, options) {
             cells: [],
             width: documentOptions.pageSize.width,
             height: documentOptions.pageSize.height,
-            sheetName: worksheets[0]?.name ?? "Sheet1",
-            worksheetCols: [],
+            sheetName: sheets[0]?.name ?? "Sheet1",
+            sheetCols: [],
             columnOffsets: [],
             columnWidths: [],
-            worksheetRows: [],
+            sheetRows: [],
             rowYPositions: [],
             rowHeights: [],
             images: []
         });
     }
-    // Fix page numbers (they may be off after combining multiple worksheets)
+    // Fix page numbers (they may be off after combining multiple sheets)
     for (let i = 0; i < allPages.length; i++) {
         allPages[i].pageNumber = i + 1;
     }
@@ -226,7 +212,7 @@ function exportPdf(workbook, options) {
     }
     // --- Step 6: Build catalog ---
     writer.addCatalog(pagesTreeObjNum, outlinesRef);
-    // --- Step 6: Add document info ---
+    // --- Step 7: Add document info ---
     writer.addInfoDict({
         title: documentOptions.title || workbook.title || undefined,
         author: documentOptions.author || workbook.creator || undefined,
@@ -241,41 +227,16 @@ function exportPdf(workbook, options) {
     // --- Step 9: Build the PDF ---
     return writer.build();
 }
-/**
- * Class-based API for PDF export (wraps {@link exportPdf}).
- *
- * @example
- * ```typescript
- * const exporter = new PdfExporter(workbook);
- * const pdfBuffer = exporter.export({ fitToPage: true });
- * ```
- */
-class PdfExporter {
-    constructor(workbook) {
-        this.workbook = workbook;
-    }
-    /**
-     * Export the workbook as a PDF document.
-     *
-     * @param options - Export options controlling layout, pagination, and appearance
-     * @returns PDF file as a Uint8Array
-     * @throws {PdfError} If the workbook has no worksheets or export fails
-     */
-    export(options) {
-        return exportPdf(this.workbook, options);
-    }
-}
-exports.PdfExporter = PdfExporter;
 // =============================================================================
-// Worksheet Selection
+// Sheet Selection
 // =============================================================================
 /**
- * Select which worksheets to export based on the options.
+ * Select which sheets to export based on the options.
  */
-function selectWorksheets(workbook, sheets) {
-    const allSheets = workbook.worksheets;
+function selectSheets(workbook, sheets) {
+    const allSheets = workbook.sheets;
     if (!sheets || sheets.length === 0) {
-        // Export all visible worksheets
+        // Export all visible sheets
         return allSheets.filter(ws => ws.state !== "hidden" && ws.state !== "veryHidden");
     }
     const result = [];
@@ -287,7 +248,7 @@ function selectWorksheets(workbook, sheets) {
             }
         }
         else if (typeof selector === "number") {
-            // 1-based position in the worksheets array
+            // 1-based position in the sheets array
             const ws = allSheets[selector - 1];
             if (ws) {
                 result.push(ws);
@@ -302,9 +263,9 @@ function selectWorksheets(workbook, sheets) {
 /**
  * Resolve user options with defaults.
  */
-function resolveOptions(options, worksheet) {
-    // Use worksheet's pageSetup as fallback for unspecified options
-    const ps = worksheet?.pageSetup;
+function resolveOptions(options, sheet) {
+    // Use sheet's pageSetup as fallback for unspecified options
+    const ps = sheet?.pageSetup;
     const pageSize = resolvePageSize(options?.pageSize, ps?.paperSize);
     const orientation = options?.orientation ?? (ps?.orientation === "landscape" ? "landscape" : "portrait");
     const margins = resolveMargins(options?.margins, ps?.margins);
@@ -314,7 +275,7 @@ function resolveOptions(options, worksheet) {
         g: 0.816,
         b: 0.816
     };
-    // Use worksheet's printTitlesRow as fallback for repeatRows
+    // Use sheet's printTitlesRow as fallback for repeatRows
     let repeatRows = options?.repeatRows ?? false;
     if (repeatRows === false && ps?.printTitlesRow) {
         // printTitlesRow format: "1:3" (repeat rows 1-3) or "1" (repeat row 1)
@@ -342,10 +303,7 @@ function resolveOptions(options, worksheet) {
         creator: options?.creator ?? "excelts"
     };
 }
-/**
- * Resolve the page size from options.
- */
-/** Map Excel PaperSize enum values to PDF page sizes. */
+/** Map PaperSize enum values to PDF page sizes. */
 const PAPER_SIZE_MAP = {
     1: types_1.PageSizes.LETTER,
     5: types_1.PageSizes.LEGAL,
@@ -361,19 +319,19 @@ function resolvePageSize(size, paperSize) {
         }
         return size;
     }
-    // Fallback to worksheet paperSize
+    // Fallback to sheet paperSize
     if (paperSize !== undefined) {
         return PAPER_SIZE_MAP[paperSize] ?? types_1.PageSizes.A4;
     }
     return types_1.PageSizes.A4;
 }
 /**
- * Resolve margins with defaults. Worksheet margins are in inches, convert to points (×72).
- * When partial PDF margins are specified, unset sides fall back to worksheet margins,
+ * Resolve margins with defaults. Sheet margins are in inches, convert to points (×72).
+ * When partial PDF margins are specified, unset sides fall back to sheet margins,
  * then to the default 72pt (1 inch).
  */
 function resolveMargins(margins, wsMargins) {
-    // Build a base from worksheet pageSetup margins (inches → points), or default 72pt
+    // Build a base from sheet pageSetup margins (inches → points), or default 72pt
     const base = wsMargins
         ? {
             top: wsMargins.top * 72,
@@ -397,7 +355,7 @@ function resolveMargins(margins, wsMargins) {
 // =============================================================================
 /**
  * Build a PDF outlines tree for sheet-level navigation.
- * Creates one bookmark entry per worksheet, pointing to the first page.
+ * Creates one bookmark entry per sheet, pointing to the first page.
  */
 function buildOutlines(writer, sheetFirstPage, pageObjNums) {
     const outlinesObjNum = writer.allocObject();

package/dist/cjs/modules/pdf/render/style-converter.js

@@ -1,9 +1,12 @@
 "use strict";
 /**
- * Converts Excel styles to PDF rendering parameters.
+ * Converts input styles to PDF rendering parameters.
  *
- * Maps Excel font, color, border, fill, and alignment properties
+ * Maps font, color, border, fill, and alignment properties
  * to their PDF equivalents for the layout engine and page renderer.
+ *
+ * This module is fully independent of the Excel module — it works with
+ * the PDF module's own style interfaces (PdfFontStyle, PdfFillData, etc.).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_COLORS = void 0;
@@ -19,8 +22,8 @@ exports.excelVAlignToPdf = excelVAlignToPdf;
 // Color Conversion
 // =============================================================================
 /**
- * Convert an Excel ARGB color string to PDF RGB color.
- * Excel uses "AARRGGBB" format (e.g., "FF000000" for black).
+ * Convert an ARGB color string to PDF RGB color.
+ * Handles "AARRGGBB" (8-char) and "RRGGBB" (6-char) formats.
  * PDF uses 0-1 floats for each component.
  */
 function argbToPdfColor(argb) {
@@ -57,7 +60,7 @@ function argbToPdfColor(argb) {
     };
 }
 /**
- * Convert an Excel Color object to PDF color.
+ * Convert a color data object to PDF color.
  * Handles both ARGB and theme-based colors.
  */
 function excelColorToPdf(color) {
@@ -74,7 +77,6 @@ function excelColorToPdf(color) {
         if (!base) {
             return null;
         }
-        // Apply tint if present (tint field exists at runtime from XLSX layer)
         const tint = color.tint;
         if (tint !== undefined && tint !== 0) {
             return applyTint(base, tint);
@@ -84,7 +86,7 @@ function excelColorToPdf(color) {
     return null;
 }
 /**
- * Map Excel theme color indices to PDF colors.
+ * Map theme color indices to PDF colors.
  * These are the default Office theme colors.
  */
 function themeColorToPdf(themeIndex) {
@@ -138,7 +140,7 @@ exports.DEFAULT_COLORS = {
 // Font Conversion
 // =============================================================================
 /**
- * Extract font properties from an Excel font for PDF rendering.
+ * Extract font properties for PDF rendering.
  */
 function extractFontProperties(font, defaultFamily, defaultSize) {
     const fontFamily = font?.name ?? defaultFamily;
@@ -154,7 +156,7 @@ function extractFontProperties(font, defaultFamily, defaultSize) {
 // Fill Conversion
 // =============================================================================
 /**
- * Convert an Excel fill to a PDF background color.
+ * Convert a fill to a PDF background color.
  * Only pattern fills with "solid" pattern are supported as PDF backgrounds.
  * Other patterns are approximated or ignored.
  */
@@ -163,21 +165,20 @@ function excelFillToPdfColor(fill) {
         return null;
     }
     if (fill.type === "pattern") {
-        const patternFill = fill;
-        if (patternFill.pattern === "solid" && patternFill.fgColor) {
-            return excelColorToPdf(patternFill.fgColor);
+        if (fill.pattern === "solid" && fill.fgColor) {
+            return excelColorToPdf(fill.fgColor);
         }
-        if (patternFill.pattern === "none") {
+        if (fill.pattern === "none") {
             return null;
         }
         // For other patterns, use fgColor as approximation
-        if (patternFill.fgColor) {
-            return excelColorToPdf(patternFill.fgColor);
+        if (fill.fgColor) {
+            return excelColorToPdf(fill.fgColor);
         }
     }
     if (fill.type === "gradient") {
         // For gradient fills, use the first stop color as approximation
-        if ("stops" in fill && fill.stops.length > 0) {
+        if (fill.stops && fill.stops.length > 0) {
             return excelColorToPdf(fill.stops[0].color);
         }
     }
@@ -187,7 +188,7 @@ function excelFillToPdfColor(fill) {
 // Border Conversion
 // =============================================================================
 /**
- * Map Excel border styles to PDF line widths and dash patterns.
+ * Map border styles to PDF line widths.
  */
 function borderStyleToLineWidth(style) {
     switch (style) {
@@ -222,7 +223,7 @@ function borderStyleToLineWidth(style) {
     }
 }
 /**
- * Map Excel border styles to PDF dash patterns.
+ * Map border styles to PDF dash patterns.
  * An empty array means a solid line.
  */
 function borderStyleToDashPattern(style) {
@@ -247,7 +248,7 @@ function borderStyleToDashPattern(style) {
     }
 }
 /**
- * Convert a single Excel border to a PDF LayoutBorder.
+ * Convert a single border side to a PDF LayoutBorder.
  */
 function convertBorder(border) {
     if (!border || !border.style) {
@@ -260,7 +261,7 @@ function convertBorder(border) {
     };
 }
 /**
- * Convert Excel Borders to PDF LayoutBorders.
+ * Convert border data to PDF LayoutBorders.
  */
 function excelBordersToPdf(borders) {
     if (!borders) {
@@ -277,7 +278,7 @@ function excelBordersToPdf(borders) {
 // Alignment Conversion
 // =============================================================================
 /**
- * Convert Excel horizontal alignment to PDF alignment.
+ * Convert horizontal alignment to PDF alignment.
  */
 function excelHAlignToPdf(alignment) {
     if (!alignment?.horizontal) {
@@ -298,11 +299,11 @@ function excelHAlignToPdf(alignment) {
     }
 }
 /**
- * Convert Excel vertical alignment to PDF alignment.
+ * Convert vertical alignment to PDF alignment.
  */
 function excelVAlignToPdf(alignment) {
     if (!alignment?.vertical) {
-        return "bottom"; // Excel default is bottom
+        return "bottom"; // Default is bottom
     }
     switch (alignment.vertical) {
         case "top":

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

@@ -1,10 +1,31 @@
 "use strict";
 /**
  * Type definitions for the PDF module.
- * Covers export options, page layout, and internal rendering models.
+ * Covers input data models, export options, page layout, and internal rendering models.
+ *
+ * The input data models (PdfWorkbook, PdfSheetData, etc.) are fully independent of
+ * the Excel module, allowing the PDF engine to be used standalone.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PageSizes = void 0;
+exports.PageSizes = exports.PdfCellType = void 0;
+// =============================================================================
+// PDF Input Data Model (Excel-independent)
+// =============================================================================
+/**
+ * Cell value type discriminator for the PDF engine.
+ */
+exports.PdfCellType = {
+    Empty: 0,
+    String: 1,
+    Number: 2,
+    Boolean: 3,
+    Date: 4,
+    RichText: 5,
+    Error: 6,
+    Formula: 7,
+    Hyperlink: 8,
+    Merge: 9
+};
 /**
  * Predefined page sizes.
  */

package/dist/esm/index.browser.js

@@ -58,7 +58,7 @@ export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString
 // =============================================================================
 // PDF Export (Browser-compatible, zero external dependencies)
 // =============================================================================
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 // =============================================================================
 // Errors
 // =============================================================================

package/dist/esm/index.js

@@ -54,7 +54,7 @@ export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString
 // =============================================================================
 // PDF Export
 // =============================================================================
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 // =============================================================================
 // Errors
 // =============================================================================