@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/types/modules/excel/xlsx/xlsx.browser.d.ts

@@ -10,7 +10,7 @@
  */
 import type { ZipTimestampMode } from "../../archive/zip-spec/timestamps.js";
 import type { PivotTableSubtotal } from "../pivot-table.js";
-import type { Workbook } from "../workbook.js";
+import type { Workbook } from "../workbook.browser.js";
 import { type IEventEmitter } from "../../stream/index.js";
 type StreamListener = Parameters<IEventEmitter["on"]>[1];
 interface EmitterLike {
@@ -101,6 +101,7 @@ export interface ZipWriterOptions {
     /** Timestamp writing strategy for ZIP entry metadata (optional). */
     timestamps?: ZipTimestampMode;
 }
+export type XlsxTemplateMode = "preserve" | "strict";
 /**
  * Options for writing an XLSX workbook.
  *
@@ -124,6 +125,54 @@ export interface XlsxWriteOptions {
      * compatibility with minimal readers.
      */
     useStyles?: boolean;
+    /**
+     * Template fidelity strategy for loaded workbooks. The default `"preserve"`
+     * byte-preserves clean chart parts and may structurally re-render edited parts
+     * when no safe raw XML patch is available. `"strict"` fails the write instead
+     * of re-rendering any edited loaded chart/chartEx part that cannot be patched
+     * in-place, preventing silent loss of unknown template XML.
+     *
+     * When a strict write fails, the thrown error enumerates the unrecognised
+     * `c15:`/`cx14:` extension paths the parser observed, so authors can decide
+     * between relaxing the mode or reshaping the mutation into a patch-friendly
+     * path. To inspect those paths *before* writing (for example to decide
+     * whether to opt into strict mode at all), use {@link Chart.unknownElements}
+     * on each chart of interest.
+     */
+    templateMode?: XlsxTemplateMode;
+    /**
+     * Convenience alias for `templateMode: "strict"`. Strict mode refuses to
+     * silently drop vendor-extension XML (`c15:…`, `cx14:…`) that the
+     * structured parser does not understand. Use this when round-tripping
+     * Excel-authored template files where preserving exotic extension
+     * elements matters more than the ability to re-render modified charts.
+     */
+    strictTemplateMode?: boolean;
+    /**
+     * Run the OOXML self-check on the produced bytes and `console.warn`
+     * every detected problem. Only {@link XLSX.writeBuffer} honours this
+     * flag — `write(stream)` / `writeFile` cannot post-validate because
+     * their output is streamed to the caller.
+     *
+     * Default resolution:
+     *   - In Node.js with `NODE_ENV !== "production"` and NOT running
+     *     under vitest (`process.env.VITEST !== "true"`): `true`.
+     *   - In production, in the browser, or under vitest: `false`.
+     *
+     * The vitest carve-out exists because running validation on every
+     * `writeBuffer` call inflates fixture `beforeAll` hooks that build
+     * hundreds of workbooks by ~50 seconds on typical hardware. Tests
+     * that want validation use {@link expectValidXlsx} directly.
+     *
+     * Pass `true` to force validation (even in production or under
+     * vitest), or `false` to suppress it (even in development). The
+     * self-check never throws: a failed validation becomes a warning so
+     * writers that intentionally produce non-conformant xlsx for
+     * testing keep working.
+     *
+     * @see OoxmlValidationReport
+     */
+    validate?: boolean;
     /**
      * Forward-compatibility / subclass extension escape hatch. Unknown keys are
      * passed through to internal writers; unrecognised keys are ignored.
@@ -176,6 +225,19 @@ declare class XLSX {
         SheetMetadata: string;
         ExternalLink: string;
         ExternalLinkPath: string;
+        Chart: string;
+        ChartEx: string;
+        ChartStyle: string;
+        ChartColors: string;
+        Drawing: string;
+        ChartUserShapes: string;
+        Chartsheet: string;
+        ThreadedComments: string;
+        Person: string;
+        Slicer: string;
+        SlicerCache: string;
+        Timeline: string;
+        TimelineCache: string;
     };
     constructor(workbook: Workbook);
     /**
@@ -204,6 +266,22 @@ declare class XLSX {
      * Shared by both Node.js write() and browser writeBuffer()
      */
     protected writeToZip(zip: IZipWriter, options?: XlsxWriteOptions): Promise<void>;
+    /**
+     * Emit the raw slicer/timeline parts captured on load. Pure
+     * byte-copy — excelts does not modify these parts. The partner
+     * Content-Types and rels are covered separately (content types in
+     * `addContentTypes`, sheet/workbook rels by the corresponding
+     * xforms consuming the existing `xl/_rels/*.rels` captured on
+     * load).
+     */
+    addSlicerAndTimelineParts(zip: IZipWriter, model: any): Promise<void>;
+    /**
+     * Write the workbook-level `xl/persons/person.xml` part when the
+     * model carries Office 365 threaded-comment authors. No-op when the
+     * persons list is empty so legacy files without threaded comments
+     * stay byte-identical.
+     */
+    addPersons(zip: IZipWriter, model: any): Promise<void>;
     /**
      * Read workbook from a stream
      */
@@ -245,15 +323,6 @@ declare class XLSX {
      * Reusable helper for passthrough and drawing processing.
      */
     protected collectStreamData(stream: IParseStream): Promise<Uint8Array>;
-    /**
-     * Check if a drawing has chart references in its relationships
-     */
-    private drawingHasChartReference;
-    /**
-     * Check if a drawing rels list references charts.
-     * Used to decide whether we need to keep raw drawing XML for passthrough.
-     */
-    private drawingRelsHasChartReference;
     /**
      * Process a known OOXML entry (workbook, styles, shared strings, etc.)
      * Returns true if handled, false if should be passed to _processDefaultEntry
@@ -277,6 +346,20 @@ declare class XLSX {
     parseWorkbook(stream: IParseStream): Promise<any>;
     parseSharedStrings(stream: IParseStream): Promise<any>;
     reconcile(model: any, options?: XlsxOptions): void;
+    /**
+     * Copy the raw bytes of each chart's user-shapes drawing part onto
+     * the owning `ChartEntry.userShapesXml` so the writer can emit them
+     * back verbatim (and so {@link Chart.userShapesXml} can surface them
+     * to user code). Runs after all ZIP entries have been processed
+     * because chart rels and drawing bytes stream in independent order.
+     *
+     * Skips charts that have no `ChartUserShapes` rel. The bytes stay
+     * keyed by drawing name (e.g. `drawing3`) inside `model.drawingRaw`
+     * since a workbook may have many user-shape drawings across
+     * different charts; we look up each chart's target through its
+     * rels file.
+     */
+    protected _reconcileChartUserShapes(model: any): void;
     /**
      * Join the three on-disk sources that together describe external workbook
      * references into a single dense `model.externalLinks: ExternalLinkModel[]`.
@@ -338,6 +421,7 @@ declare class XLSX {
         subtotal?: string;
     }>, defaultMetric: PivotTableSubtotal): PivotTableSubtotal[];
     _processWorksheetEntry(stream: IParseStream, model: any, sheetNo: number, options: XlsxOptions | undefined, path: string): Promise<void>;
+    _processChartsheetEntry(stream: IParseStream, model: any, sheetNo: number): Promise<void>;
     _processCommentEntry(stream: IParseStream, model: any, zipPath: string): Promise<void>;
     _processTableEntry(stream: IParseStream, model: any, zipPath: string): Promise<void>;
     _processWorksheetRelsEntry(stream: IParseStream, model: any, sheetNo: number): Promise<void>;
@@ -351,6 +435,15 @@ declare class XLSX {
      * @param rawData - Pre-read raw data (used in loadFromFiles path to avoid re-reading stream)
      */
     _processDrawingEntry(stream: IParseStream, model: any, name: string, rawData?: Uint8Array): Promise<void>;
+    /**
+     * Stash raw bytes of a chart-overlay drawing part. `c:userShapes`
+     * parts live under `xl/drawings/chartUserShape{N}.xml` in files we
+     * write ourselves and can use arbitrary names in foreign files (the
+     * rel target is the only authoritative reference). The bytes are
+     * keyed by the stem so `_reconcileChartUserShapes` can match them
+     * against each chart's `ChartUserShapes` rel Target.
+     */
+    _processChartUserShapesEntry(_stream: IParseStream, model: any, name: string, rawData?: Uint8Array): Promise<void>;
     _processDrawingRelsEntry(entry: any, model: any, name: string): Promise<void>;
     _processVmlDrawingEntry(entry: any, model: any, zipPath: string): Promise<void>;
     _processVmlDrawingHFEntry(entry: any, model: any, _name: string): Promise<void>;
@@ -373,17 +466,16 @@ declare class XLSX {
      * paths like `"测试.xlsx"`).
      */
     _processExternalLinkRelsEntry(stream: IParseStream, model: any, index: number): Promise<void>;
+    _processChartEntry(stream: IParseStream, model: any, chartNumber: number, rawData?: Uint8Array): Promise<void>;
+    _processChartRelsEntry(stream: IParseStream, model: any, chartNumber: number): Promise<void>;
+    _processChartStyleEntry(stream: IParseStream, model: any, styleNumber: number): Promise<void>;
+    _processChartColorsEntry(stream: IParseStream, model: any, colorsNumber: number): Promise<void>;
     loadFromFiles(zipData: Record<string, Uint8Array>, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Process default entries (drawings, comments, tables, etc.)
      * @param rawData Optional raw entry data for passthrough preservation (used by loadFromFiles)
      */
     protected _processDefaultEntry(stream: IParseStream, model: any, entryName: string, rawData?: Uint8Array): Promise<boolean>;
-    /**
-     * Store a passthrough file for preservation during read/write cycles.
-     * These files are not parsed but stored as raw bytes to be written back unchanged.
-     */
-    _processPassthroughEntry(stream: IParseStream, model: any, entryName: string): Promise<void>;
     /**
      * Helper: render an xform directly to a streaming zip entry.
      * Avoids buffering the entire XML string in memory.
@@ -402,7 +494,12 @@ declare class XLSX {
     addStyles(zip: IZipWriter, model: any): Promise<void>;
     addWorkbook(zip: IZipWriter, model: any): Promise<void>;
     addWorksheets(zip: IZipWriter, model: any): Promise<void>;
+    addChartsheets(zip: IZipWriter, model: any): Promise<void>;
     addDrawings(zip: IZipWriter, model: any): Promise<void>;
+    addCharts(zip: IZipWriter, model: any, strictTemplateMode?: boolean): Promise<void>;
+    addChartExEntries(zip: IZipWriter, model: any, strictTemplateMode?: boolean): Promise<void>;
+    private _appendChartExSidecars;
+    private _buildChartExRels;
     addTables(zip: IZipWriter, model: any): Promise<void>;
     /**
      * Write every external workbook reference into the archive. For each
@@ -415,16 +512,13 @@ declare class XLSX {
      * relative** `Target` whenever the user supplied one. This is the single
      * line that makes Office / WPS resolve the referenced workbook relative
      * to the current file's directory (not the `%USERPROFILE%\Documents`
-     * fallback) — the root of the behaviour reported in exceljs#3039.
+     * fallback) — the root of the relative-path external-link behaviour.
      */
     addExternalLinks(zip: IZipWriter, model: any): Promise<void>;
-    /**
-     * Write passthrough files (charts, etc.) that were preserved during read.
-     * These files are written back unchanged to preserve unsupported features.
-     */
-    addPassthrough(zip: IZipWriter, model: any): void;
     addPivotTables(zip: IZipWriter, model: any): Promise<void>;
     _finalize(zip: IZipWriter): Promise<this>;
     prepareModel(model: any, options: any): void;
+    prepareChartExSidecars(model: any): void;
+    prepareChartsheets(model: any): void;
 }
 export { XLSX };

package/dist/types/modules/pdf/builder/document-builder.d.ts

@@ -47,6 +47,26 @@ export interface DrawTextOptions {
     maxWidth?: number;
     /** Line height multiplier. Default: 1.2. */
     lineHeight?: number;
+    /**
+     * Rotation in degrees, counter-clockwise in the PDF coordinate system
+     * (which has +Y pointing up, so visually clockwise on a page viewer).
+     * The rotation pivot is `(x, y)`. Default: `0` (no rotation).
+     *
+     * Incompatible with `maxWidth` (word-wrapping + rotation requires per-
+     * line matrix transforms that the current implementation does not
+     * support — supplying both leaves the wrap ignoring rotation so the
+     * text remains readable). If you need rotated wrapped text, break it
+     * into lines yourself and call `drawText` per line.
+     */
+    rotation?: number;
+    /**
+     * Horizontal alignment of the text around `x`. Default: `"start"`
+     * (the conventional PDF behaviour where `x` is the baseline left
+     * edge). Implemented by pre-shifting `x` using the chosen font's
+     * measured width — no deferred layout, so the computed position is
+     * stable across font subsetting.
+     */
+    anchor?: "start" | "middle" | "end";
 }
 /** Rectangle drawing options. */
 export interface DrawRectOptions {
@@ -158,6 +178,19 @@ export interface DrawImageOptions {
     /** Display height in points. */
     height: number;
 }
+/** Options for drawing a simple SVG document onto a PDF page. */
+export interface DrawSvgOptions {
+    /** Raw SVG markup. */
+    svg: string;
+    /** Destination X position in points. */
+    x: number;
+    /** Destination Y position in points. */
+    y: number;
+    /** Destination width in points. If omitted, uses the SVG width/viewBox width. */
+    width?: number;
+    /** Destination height in points. If omitted, uses the SVG height/viewBox height. */
+    height?: number;
+}
 /** Document metadata. */
 export interface DocumentMetadata {
     title?: string;
@@ -392,6 +425,13 @@ export declare class PdfPageBuilder {
      * @param options - Fill/stroke options
      */
     drawSvgPath(d: string, options?: DrawPathOptions): this;
+    /**
+     * Draw a simple SVG document onto this page.
+     *
+     * Supports the SVG primitives emitted by ExcelTS chart rendering:
+     * `rect`, `line`, `circle`, `polyline`, `polygon`, `path`, and `text`.
+     */
+    drawSvg(options: DrawSvgOptions): this;
     /**
      * Get the raw content stream for advanced operations.
      * Use this when the high-level API doesn't cover your use case.
@@ -413,6 +453,21 @@ export declare class PdfDocumentBuilder {
     private _embeddedFont;
     private _pdfA;
     private _signatureOptions;
+    /**
+     * Sink for non-fatal diagnostics produced during `build()`. Populated by
+     * {@link onWarning}; defaults to undefined so unaware consumers see
+     * pre-diagnostic behaviour unchanged. Fires for every warning in a
+     * single build, not just the first.
+     */
+    private _onWarning;
+    /**
+     * Set via {@link disableFontAutoDiscovery} — opts out of the system-font
+     * auto-embed path in `build()`. Authors who need byte-stable output
+     * across machines (golden tests, reproducible build pipelines) should
+     * enable this so a host-only CJK font doesn't sneak into one run but
+     * not another.
+     */
+    private _disableFontAutoDiscovery;
     /**
      * Add a new blank page to the document.
      *
@@ -434,6 +489,25 @@ export declare class PdfDocumentBuilder {
      * @param fontBytes - Raw .ttf file bytes
      */
     embedFont(fontBytes: Uint8Array): this;
+    /**
+     * Register a callback invoked once per non-fatal diagnostic during
+     * `build()`. Currently raised for:
+     *
+     * - auto-embedded system fonts (`'Auto-embedded system font ...'`)
+     * - non-WinAnsi characters with no covering font (`'...non-WinAnsi character(s) present...'`)
+     *
+     * The callback is synchronous and runs inside `build()`; throwing
+     * from it will abort the build. Return value is ignored.
+     */
+    onWarning(handler: (message: string) => void): this;
+    /**
+     * Opt out of the best-effort system-font auto-discovery that `build()`
+     * performs when the document contains non-WinAnsi characters and no
+     * font was explicitly embedded. Use this to keep output byte-stable
+     * across hosts: one machine may have SimSun installed while another
+     * does not.
+     */
+    disableFontAutoDiscovery(): this;
     /**
      * Enable PDF/A compliance output.
      *

package/dist/types/modules/pdf/excel-bridge.d.ts

@@ -14,6 +14,7 @@
  * const pdf = await excelToPdf(workbook);
  * ```
  */
+import type { Chart, RegionMapDataOptions } from "../excel/chart/index.js";
 import type { Workbook } from "../excel/workbook.js";
 import { type PdfExportOptions } from "./types.js";
 /**
@@ -28,3 +29,71 @@ import { type PdfExportOptions } from "./types.js";
  * @returns Promise of PDF file as a Uint8Array
  */
 export declare function excelToPdf(workbook: Workbook, options?: PdfExportOptions): Promise<Uint8Array>;
+/**
+ * Options for {@link chartToPdf}.
+ */
+export interface ChartToPdfOptions {
+    /** PDF page width in points. Default: max(chart width + 72, 400). */
+    pageWidth?: number;
+    /** PDF page height in points. Default: max(chart height + 72, 300). */
+    pageHeight?: number;
+    /** Chart render width in points. Default: 520. */
+    width?: number;
+    /** Chart render height in points. Default: 360. */
+    height?: number;
+    /**
+     * Left margin in points between the chart and the page edge. Default: 36.
+     * Used as top margin too so the chart sits in a 36-pt gutter.
+     */
+    margin?: number;
+    /**
+     * Force rasterisation even for classic charts. Default: `false`
+     * (classic charts render as vector PDF content; ChartEx charts
+     * also render as vector when their layout IDs are supported — see
+     * `VECTOR_PDF_CHART_EX_LAYOUT_IDS` and the "ChartEx PDF" note in
+     * `src/modules/excel/README.md`). When `true`, all chart types go
+     * through the SVG → PNG → image-XObject raster pipeline.
+     */
+    forceRaster?: boolean;
+    /** PNG raster scale multiplier when rasterising. Default: 2 (for crisp text). */
+    rasterScale?: number;
+    /** Document metadata forwarded to the resulting PDF. */
+    title?: string;
+    author?: string;
+    /**
+     * ChartEx `regionMap` data. When supplied, the vector PDF path
+     * uses the TopoJSON polygons (matched via `match` rules) instead
+     * of the centroid preview. Ignored for non-regionMap layouts and
+     * when the chart rasterises. Mirrors `renderChartExSvg`'s
+     * `regionMap` option so a single caller-side object works for
+     * both backends.
+     */
+    regionMap?: RegionMapDataOptions;
+}
+/**
+ * Render a single {@link Chart} to a standalone one-page PDF.
+ *
+ * The output is a **zero-dependency deterministic preview**, not an
+ * Excel-pixel-perfect rendering. Use this for server-side reports,
+ * thumbnails, and CI artefacts where the goal is a recognisable chart
+ * without a headless Office dependency. When pixel-identical output
+ * matters (publication-grade reports, Excel/LibreOffice-compatible
+ * formatting), round-trip the `.xlsx` through
+ * `soffice --convert-to pdf` — the byte-preserving round-trip in this
+ * library makes that a safe handoff. See `src/modules/excel/README.md`
+ * → "Rendering scope" for the complete boundary list.
+ *
+ * Classic charts take the **vector** path: the chart is drawn directly
+ * onto the page via `drawChartPdf`, so text stays selectable and shapes
+ * remain resolution-independent. ChartEx charts whose layout IDs are in
+ * `VECTOR_PDF_CHART_EX_LAYOUT_IDS` also take the vector path via
+ * `drawChartExPdf`; unsupported layouts (if any) and charts where
+ * `forceRaster: true` is set fall through to the SVG → PNG → image-XObject
+ * raster pipeline.
+ *
+ * Lives in `excel-bridge.ts` because invoking the PDF builder from the
+ * chart module would cross the Layer 4 → Layer 5 import boundary
+ * documented in `AGENTS.md`. Consumers import it from
+ * `@cj-tech-master/excelts/pdf` alongside `excelToPdf`.
+ */
+export declare function chartToPdf(chart: Chart, options?: ChartToPdfOptions): Promise<Uint8Array>;

package/dist/types/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/types/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/types/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/types/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.