@cj-tech-master/excelts 6.2.0 → 7.0.0

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

@@ -1,26 +1,18 @@
 /**
- * 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.
  */
 import { PdfWriter } from "../core/pdf-writer.js";
 import { PdfDict, pdfRef, pdfNumber, pdfString as pdfStr } from "../core/pdf-object.js";
 import { FontManager, resolvePdfFontName } from "../font/font-manager.js";
 import { parseTtf } from "../font/ttf-parser.js";
 import { initEncryption } from "../core/encryption.js";
-import { layoutWorksheet } from "./layout-engine.js";
+import { layoutSheet } from "./layout-engine.js";
 import { renderPage, alphaGsName } from "./page-renderer.js";
 import { decodePng } from "./png-decoder.js";
 import { PdfError, PdfRenderError } from "../errors.js";
@@ -30,22 +22,17 @@ import { argbToPdfColor } from "./style-converter.js";
 // 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
  */
 export function exportPdf(workbook, options) {
-    const worksheets = selectWorksheets(workbook, options?.sheets);
-    if (worksheets.length === 0) {
-        throw new 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 PdfError("No sheets to export. The workbook is empty or no sheets matched.");
     }
     const fontManager = new FontManager();
     const writer = new PdfWriter();
@@ -59,19 +46,19 @@ export function exportPdf(workbook, options) {
             throw new 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 = layoutWorksheet(worksheet, resolved, fontManager);
+            const resolved = resolveOptions(options, sheet);
+            const pages = layoutSheet(sheet, resolved, fontManager);
             allPages.push(...pages);
         }
         catch (err) {
-            throw new PdfRenderError(`Failed to layout worksheet "${worksheet.name}"`, { cause: err });
+            throw new 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({
@@ -80,17 +67,17 @@ export 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;
     }
@@ -222,7 +209,7 @@ export 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,
@@ -237,40 +224,16 @@ export 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 });
- * ```
- */
-export 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);
-    }
-}
 // =============================================================================
-// 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 = [];
@@ -282,7 +245,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);
@@ -297,9 +260,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);
@@ -309,7 +272,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)
@@ -337,10 +300,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: PageSizes.LETTER,
     5: PageSizes.LEGAL,
@@ -356,19 +316,19 @@ function resolvePageSize(size, paperSize) {
         }
         return size;
     }
-    // Fallback to worksheet paperSize
+    // Fallback to sheet paperSize
     if (paperSize !== undefined) {
         return PAPER_SIZE_MAP[paperSize] ?? PageSizes.A4;
     }
     return 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,
@@ -392,7 +352,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/esm/modules/pdf/render/style-converter.js

@@ -1,15 +1,18 @@
 /**
- * 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.).
  */
 // =============================================================================
 // 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.
  */
 export function argbToPdfColor(argb) {
@@ -46,7 +49,7 @@ export 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.
  */
 export function excelColorToPdf(color) {
@@ -63,7 +66,6 @@ export 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);
@@ -73,7 +75,7 @@ export 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) {
@@ -127,7 +129,7 @@ export const DEFAULT_COLORS = {
 // Font Conversion
 // =============================================================================
 /**
- * Extract font properties from an Excel font for PDF rendering.
+ * Extract font properties for PDF rendering.
  */
 export function extractFontProperties(font, defaultFamily, defaultSize) {
     const fontFamily = font?.name ?? defaultFamily;
@@ -143,7 +145,7 @@ export 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.
  */
@@ -152,21 +154,20 @@ export 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);
         }
     }
@@ -176,7 +177,7 @@ export 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) {
@@ -211,7 +212,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) {
@@ -236,7 +237,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) {
@@ -249,7 +250,7 @@ function convertBorder(border) {
     };
 }
 /**
- * Convert Excel Borders to PDF LayoutBorders.
+ * Convert border data to PDF LayoutBorders.
  */
 export function excelBordersToPdf(borders) {
     if (!borders) {
@@ -266,7 +267,7 @@ export function excelBordersToPdf(borders) {
 // Alignment Conversion
 // =============================================================================
 /**
- * Convert Excel horizontal alignment to PDF alignment.
+ * Convert horizontal alignment to PDF alignment.
  */
 export function excelHAlignToPdf(alignment) {
     if (!alignment?.horizontal) {
@@ -287,11 +288,11 @@ export function excelHAlignToPdf(alignment) {
     }
 }
 /**
- * Convert Excel vertical alignment to PDF alignment.
+ * Convert vertical alignment to PDF alignment.
  */
 export function excelVAlignToPdf(alignment) {
     if (!alignment?.vertical) {
-        return "bottom"; // Excel default is bottom
+        return "bottom"; // Default is bottom
     }
     switch (alignment.vertical) {
         case "top":

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

@@ -1,7 +1,28 @@
 /**
  * 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.
  */
+// =============================================================================
+// PDF Input Data Model (Excel-independent)
+// =============================================================================
+/**
+ * Cell value type discriminator for the PDF engine.
+ */
+export const PdfCellType = {
+    Empty: 0,
+    String: 1,
+    Number: 2,
+    Boolean: 3,
+    Date: 4,
+    RichText: 5,
+    Error: 6,
+    Formula: 7,
+    Hyperlink: 8,
+    Merge: 9
+};
 /**
  * Predefined page sizes.
  */