@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/types/index.browser.d.ts

@@ -2,7 +2,7 @@
  * Browser entry point - No Node.js dependencies
  * This version is optimized for browser environments with minimal bundle size
  */
-export { Workbook } from "./modules/excel/workbook.js";
+export { Workbook } from "./modules/excel/workbook.browser.js";
 export { Worksheet } from "./modules/excel/worksheet.js";
 export { Row } from "./modules/excel/row.js";
 export { Column } from "./modules/excel/column.js";
@@ -18,27 +18,30 @@ export * from "./modules/excel/enums.js";
 export * from "./modules/excel/types.js";
 export { createTextWatermarkImage } from "./modules/excel/utils/watermark-image.js";
 export type { TextWatermarkImageOptions } from "./modules/excel/utils/watermark-image.js";
-export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, CacheField, SharedItemValue, DataField, PivotTableSubtotal, RecordValue, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
+export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, CacheField, SharedItemValue, DataField, PivotTableChartFormat, PivotTableSubtotal, RecordValue, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
 export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 export { WorkbookWriter } from "./modules/excel/stream/workbook-writer.browser.js";
 export { WorkbookReader } from "./modules/excel/stream/workbook-reader.browser.js";
 export { WorksheetWriter } from "./modules/excel/stream/worksheet-writer.js";
 export { WorksheetReader } from "./modules/excel/stream/worksheet-reader.js";
-export type { CsvOptions, CsvInput } from "./modules/excel/workbook.js";
+export type { CsvOptions, CsvInput } from "./modules/excel/workbook.browser.js";
 export { CsvParserStream, CsvFormatterStream, createCsvParserStream, createCsvFormatterStream } from "./modules/csv/stream/index.js";
 export type { MarkdownOptions } from "./modules/markdown/types.js";
 export type { MarkdownAlignment, MarkdownParseResult, MarkdownParseOptions, MarkdownColumnConfig, MarkdownFormatOptions } from "./modules/markdown/types.js";
 export { DefinedNames, type DefinedNameModel } from "./modules/excel/defined-names.js";
+export { Chartsheet } from "./modules/excel/chartsheet.js";
+export type { AddChartsheetOptions, AddPivotChartsheetOptions, ChartsheetOptions, ChartsheetViewOptions } from "./modules/excel/chartsheet.js";
 export type { CheckboxState } from "./modules/excel/form-control.js";
 export type { ColumnDefn, ColumnHeaderValue } from "./modules/excel/column.js";
 export type { RangeInput } from "./modules/excel/range.js";
-export type { WorkbookModel, WorkbookMedia, WorkbookProtectionModel, ExternalLinkModel, ExternalLinkCachedSheet } from "./modules/excel/workbook.js";
+export type { WorkbookModel, WorkbookMedia, WorkbookProtectionModel, ExternalLinkModel, ExternalLinkCachedSheet } from "./modules/excel/workbook.browser.js";
+export { getCellDisplayText, formatCellValue, isDateDisplayFormat } from "./modules/excel/utils/cell-format.js";
 export { decodeCol, encodeCol, decodeRow, encodeRow, decodeCell, encodeCell, decodeRange, encodeRange } from "./modules/excel/utils/address.js";
 export type { CellAddress, SheetRange, Origin } from "./modules/excel/utils/address.js";
 export type { SheetToJSONOptions, AddJSONOptions, AddAOAOptions } from "./modules/excel/worksheet.js";
 export { dateToExcel, excelToDate } from "./utils/utils.base.js";
 export { base64ToUint8Array, uint8ArrayToBase64 } from "./utils/utils.base.js";
-export { xmlEncode, xmlDecode } from "./modules/xml/encode.js";
+export { xmlEncode, xmlDecode, xmlEncodeAttr, validateXmlName } from "./modules/xml/encode.js";
 export { DateParser, DateFormatter, getSupportedFormats, type DateFormat } from "./utils/datetime.js";
 export { BaseError, type BaseErrorOptions, toError, errorToJSON, getErrorChain, getRootCause } from "./utils/errors.js";
 export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString } from "./utils/binary.js";

package/dist/types/index.d.ts

@@ -18,7 +18,7 @@ export * from "./modules/excel/enums.js";
 export * from "./modules/excel/types.js";
 export { createTextWatermarkImage } from "./modules/excel/utils/watermark-image.js";
 export type { TextWatermarkImageOptions } from "./modules/excel/utils/watermark-image.js";
-export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, CacheField, SharedItemValue, DataField, PivotTableSubtotal, RecordValue, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
+export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, CacheField, SharedItemValue, DataField, PivotTableChartFormat, PivotTableSubtotal, RecordValue, ParsedCacheDefinition, ParsedCacheRecords } from "./modules/excel/pivot-table.js";
 export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "./modules/excel/stream/workbook-reader.js";
 export type { WorksheetReaderOptions, WorksheetEvent, RowEvent, HyperlinkEvent, WorksheetHyperlink } from "./modules/excel/stream/worksheet-reader.js";
@@ -28,6 +28,8 @@ export { CsvParserStream, CsvFormatterStream, createCsvParserStream, createCsvFo
 export type { MarkdownOptions } from "./modules/markdown/types.js";
 export type { MarkdownAlignment, MarkdownParseResult, MarkdownParseOptions, MarkdownColumnConfig, MarkdownFormatOptions } from "./modules/markdown/types.js";
 export { DefinedNames, type DefinedNameModel } from "./modules/excel/defined-names.js";
+export { Chartsheet } from "./modules/excel/chartsheet.js";
+export type { AddChartsheetOptions, AddPivotChartsheetOptions, ChartsheetOptions, ChartsheetViewOptions } from "./modules/excel/chartsheet.js";
 export type { CheckboxState } from "./modules/excel/form-control.js";
 export type { ColumnDefn, ColumnHeaderValue } from "./modules/excel/column.js";
 export type { RangeInput } from "./modules/excel/range.js";
@@ -39,7 +41,7 @@ export type { SheetToJSONOptions, AddJSONOptions, AddAOAOptions } from "./module
 export { getCellDisplayText, formatCellValue, isDateDisplayFormat } from "./modules/excel/utils/cell-format.js";
 export { dateToExcel, excelToDate } from "./utils/utils.base.js";
 export { base64ToUint8Array, uint8ArrayToBase64 } from "./utils/utils.base.js";
-export { xmlEncode, xmlDecode } from "./modules/xml/encode.js";
+export { xmlEncode, xmlDecode, xmlEncodeAttr, validateXmlName } from "./modules/xml/encode.js";
 export { DateParser, DateFormatter, getSupportedFormats, type DateFormat } from "./utils/datetime.js";
 export { BaseError, type BaseErrorOptions, toError, errorToJSON, getErrorChain, getRootCause } from "./utils/errors.js";
 export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString } from "./utils/binary.js";

package/dist/types/modules/excel/chart/cache-populator.d.ts

@@ -0,0 +1,49 @@
+import type { ChartExModel } from "./chart-ex-types.js";
+/**
+ * Chart cache populator.
+ *
+ * Walks a ChartModel, finds every `numRef`/`strRef` formula, resolves it against
+ * the actual worksheet cell values in the workbook, and populates the cache
+ * points so that headless consumers (PDF export, image preview, other readers
+ * that don't recalculate formulas) see non-empty charts.
+ *
+ * Excel itself recomputes caches on open, so this is a best-effort enrichment:
+ *   - empty/missing cells produce null values at the correct index
+ *   - formula-bearing cells use their cached result when available
+ *   - non-existent sheets or malformed formulas are skipped silently
+ */
+import type { ChartModel, NumberReference, StringReference, MultiLevelStringReference } from "./types.js";
+import type { Workbook } from "../workbook.js";
+import type { Worksheet } from "../worksheet.js";
+/**
+ * Populate all number/string caches in a ChartModel from the given workbook.
+ * Mutates the model in place. Safe to call multiple times (idempotent).
+ *
+ * @param model - The chart model to enrich
+ * @param workbook - The workbook used to resolve sheet/cell references
+ * @param contextWorksheet - Optional worksheet providing the default scope for
+ *   defined-name resolution. When a defined name has a sheet-scoped entry
+ *   matching this worksheet's workbook index (`localSheetId`), that entry
+ *   wins over the workbook-scoped entry. Supplying this argument is required
+ *   to correctly resolve sheet-scoped names; omitting it falls back to
+ *   workbook-scoped names only.
+ */
+export declare function fillChartCaches(model: ChartModel, workbook: Workbook, contextWorksheet?: Worksheet): void;
+export declare function fillChartExCaches(model: ChartExModel, workbook: Workbook, contextWorksheet?: Worksheet): void;
+/**
+ * Populate a NumberReference cache from the workbook.
+ * Only fills if `cache.points` is currently empty.
+ *
+ * @param contextWorksheet - Optional worksheet whose sheet-scoped defined
+ *   names take precedence over workbook-scoped ones.
+ */
+export declare function fillNumRef(ref: NumberReference, workbook: Workbook, date1904?: boolean, contextWorksheet?: Worksheet): void;
+/**
+ * Populate a StringReference cache from the workbook.
+ * Only fills if `cache.points` is currently empty.
+ *
+ * @param contextWorksheet - Optional worksheet whose sheet-scoped defined
+ *   names take precedence over workbook-scoped ones.
+ */
+export declare function fillStrRef(ref: StringReference, workbook: Workbook, contextWorksheet?: Worksheet): void;
+export declare function fillMultiLvlStrRef(ref: MultiLevelStringReference, workbook: Workbook, contextWorksheet?: Worksheet): void;

package/dist/types/modules/excel/chart/chart-api.d.ts

@@ -0,0 +1,92 @@
+import type { Table } from "../table.js";
+import type { Worksheet } from "../worksheet.js";
+import type { AddChartExOptions } from "./chart-ex-types.js";
+import type { AddChartOptions, AddChartSeriesOptions } from "./types.js";
+export interface SeriesFromColumnsOptions {
+    categories?: string;
+    values: string;
+    name?: AddChartSeriesOptions["name"];
+}
+export interface AddChartFromTableOptions extends Omit<AddChartOptions, "series"> {
+    categoryColumn?: string | number;
+    valueColumns?: Array<string | number>;
+    /** Use Excel structured references so charts expand with the table. Default: true. */
+    structuredReferences?: boolean;
+}
+export interface AddChartFromRowsOptions<T extends Record<string, unknown>> extends Omit<AddChartOptions, "series"> {
+    x: keyof T & string;
+    y: (keyof T & string) | Array<keyof T & string>;
+    sheetName?: string;
+    startCell?: string;
+    includeHeaders?: boolean;
+}
+export declare function seriesFromColumns(sheetName: string, options: SeriesFromColumnsOptions): AddChartSeriesOptions;
+export declare function chartOptionsFromTable(worksheet: Worksheet, table: Table | string, options: AddChartFromTableOptions): AddChartOptions;
+export declare function chartOptionsFromRows<T extends Record<string, unknown>>(worksheet: Worksheet, rows: T[], options: AddChartFromRowsOptions<T>): AddChartOptions;
+/**
+ * Shared options for ChartEx helpers that derive series references from an
+ * existing worksheet Table. The `type` is narrowed per-helper (histogram,
+ * sunburst, treemap, waterfall, funnel, pareto, boxWhisker) because
+ * `regionMap` requires geographic labels that don't map cleanly from a
+ * generic category column. Column resolution mirrors
+ * {@link AddChartFromTableOptions}: string matches the header
+ * case-insensitively, number is a 0-based index.
+ */
+export interface AddChartExFromTableOptions extends Omit<AddChartExOptions, "series" | "categories"> {
+    /**
+     * The category column. String is matched case-insensitively against the
+     * table header; number is a 0-based index. Default: 0.
+     */
+    categoryColumn?: string | number;
+    /**
+     * The value columns. Each produces one `cx:series`. Defaults to every
+     * non-category column.
+     */
+    valueColumns?: Array<string | number>;
+    /**
+     * Use Excel structured references (`Table1[Col]`) so the chart tracks
+     * table expansion. Default: true. When `false`, classic absolute
+     * ranges (`Sheet1!$B$2:$B$10`) are emitted instead.
+     */
+    structuredReferences?: boolean;
+}
+/**
+ * Shared options for ChartEx helpers that derive series from a plain
+ * JavaScript object array, mirroring {@link AddChartFromRowsOptions}. The
+ * helper writes the rows into the worksheet first (headers optional) and
+ * then emits the corresponding absolute ranges.
+ */
+export interface AddChartExFromRowsOptions<T extends Record<string, unknown>> extends Omit<AddChartExOptions, "series" | "categories"> {
+    /** Key used as the category column. */
+    x: keyof T & string;
+    /**
+     * Key(s) used as value column(s). Each produces one `cx:series`.
+     */
+    y: (keyof T & string) | Array<keyof T & string>;
+    /** Target worksheet name. Must match the worksheet this helper is invoked on. */
+    sheetName?: string;
+    /** Top-left cell for the staged data. Default: `A1`. */
+    startCell?: string;
+    /** Emit a header row before the data. Default: `true`. */
+    includeHeaders?: boolean;
+}
+/**
+ * Build an {@link AddChartExOptions} bundle by pointing at a worksheet Table.
+ *
+ * Mirrors {@link chartOptionsFromTable} for classic charts. The builder
+ * resolves the table's data range and populates `categories` + one
+ * series per value column. `regionMap` is intentionally unsupported
+ * because its data model expects geographic labels that don't fit a
+ * flat-column helper — use {@link buildChartExModel} directly.
+ */
+export declare function chartExOptionsFromTable(worksheet: Worksheet, table: Table | string, options: AddChartExFromTableOptions & {
+    type: Exclude<AddChartExOptions["type"], "regionMap">;
+}): AddChartExOptions;
+/**
+ * Build an {@link AddChartExOptions} bundle from a plain object-array
+ * dataset, staging the rows into the worksheet before emitting ranges.
+ * Mirrors {@link chartOptionsFromRows} for classic charts.
+ */
+export declare function chartExOptionsFromRows<T extends Record<string, unknown>>(worksheet: Worksheet, rows: T[], options: AddChartExFromRowsOptions<T> & {
+    type: Exclude<AddChartExOptions["type"], "regionMap">;
+}): AddChartExOptions;

package/dist/types/modules/excel/chart/chart-builder.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Chart Builder - Constructs a ChartModel from simplified AddChartOptions.
+ *
+ * This bridges the high-level API (worksheet.addChart) to the full
+ * OOXML chart model that the XForm layer serialises.
+ */
+import type { AddChartOptions, AddChartSeriesOptions, AddComboChartOptions, AddShapeFillOptions, ChartModel, SeriesBase, ShapeProperties, ChartColor } from "./types.js";
+/**
+ * Normalise a user-facing hex colour into a structured {@link ChartColor}.
+ * Accepts `"#RRGGBB"` / `"RRGGBB"` and the optional 8-digit
+ * `"RRGGBBAA"` form. The alpha byte, when present, is decoded into
+ * `color.alpha` on the OOXML 0–100000 scale (0 = fully transparent,
+ * 100000 = fully opaque) rather than discarded. Throws
+ * `ChartOptionsError` when the input is not a valid hex triplet so the
+ * caller sees the mistake at the assignment site rather than via a
+ * downstream XML parser rejection.
+ */
+export declare function hexToColor(hex: string): ChartColor;
+/**
+ * Convert a simplified AddShapeFillOptions (or a pre-built ShapeProperties)
+ * into a structured ShapeProperties object. Returns undefined when input is
+ * undefined.
+ */
+/**
+ * Normalise a user-facing shape-fill option bundle (hex-string fill,
+ * hex-string border, borderWidth in points, gradient, pattern, …) into a
+ * structured {@link ShapeProperties}. Passes through already-structured
+ * shapes unchanged so callers can mix the two forms freely.
+ *
+ * Exported so `chart-ex-builder` can reuse the exact same normalisation
+ * for ChartEx `spPr` options — previously ChartEx only accepted the
+ * fully-structured form, which was an API asymmetry.
+ */
+export declare function toShapeProperties(input: ShapeProperties | AddShapeFillOptions | undefined): ShapeProperties | undefined;
+export declare function buildChartSeriesForType(chartType: AddChartOptions["type"], options: AddChartSeriesOptions, index: number): SeriesBase;
+export declare function applyChartSeriesOptionsPatch(series: SeriesBase, options: Partial<AddChartSeriesOptions>, chartType?: AddChartOptions["type"]): void;
+/**
+ * Build a full ChartModel from the simplified AddChartOptions.
+ */
+export declare function buildChartModel(opts: AddChartOptions): ChartModel;
+/**
+ * Build a combo chart model with multiple chart type groups.
+ *
+ * Each group can optionally be plotted on secondary axes.
+ * The builder creates primary axes for the first group that needs
+ * them, and secondary axes for any group with `useSecondaryAxis: true`.
+ */
+export declare function buildComboChartModel(opts: AddComboChartOptions): ChartModel;

package/dist/types/modules/excel/chart/chart-ex-builder.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ChartEx builder — constructs a ChartExModel from simplified AddChartExOptions.
+ *
+ * Each layoutId corresponds to a distinct chart type. The builder produces a
+ * structured model that the renderer serialises to `cx:chart` XML.
+ */
+import type { AddChartExOptions, ChartExModel } from "./chart-ex-types.js";
+/**
+ * Combine multiple single-column range formulas (first item is the
+ * OUTERMOST hierarchy level, last item is the leaf level / primary
+ * category) into a single multi-column range that Excel's hierarchical
+ * chartEx loader accepts.
+ *
+ * Microsoft Excel's treemap / sunburst writer emits ONE `<cx:strDim>`
+ * whose `<cx:f>` points at a contiguous multi-column range spanning
+ * every hierarchy level (e.g. `Sheet1!$A$2:$C$8` for a Region / Country
+ * / City breakdown). The chart reader derives the hierarchy from the
+ * column ORDER within that range — the first column is the root and
+ * the last is the leaf. Emitting per-level `<cx:strDim>` siblings (one
+ * per formula) is schema-legal but makes Excel draw an empty plot
+ * area: verified against `reference-hierarchy.xlsx` (Excel-authored
+ * sample) where the same hierarchy renders correctly only when the
+ * columns live under a single `<cx:f>`.
+ *
+ * Returns the combined formula when every input formula lives on the
+ * same sheet with identical row spans and contiguous ascending columns
+ * (the common case when authors lay their hierarchy out in adjacent
+ * worksheet columns). Returns `null` otherwise — the caller should
+ * fall back to per-level caching because Excel has no way to express
+ * a non-contiguous hierarchy as a single range.
+ */
+export declare function combineHierarchyFormulas(formulas: readonly string[]): string | null;
+/**
+ * Build a structured ChartExModel from high-level options.
+ */
+export declare function buildChartExModel(opts: AddChartExOptions): ChartExModel;

package/dist/types/modules/excel/chart/chart-ex-parser.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Best-effort ChartEx parser for Office 2016+ cx: chart XML.
+ *
+ * The parser captures the structured fields that ExcelTS can render and keeps
+ * the original XML on the model so clean round-trips can still use raw bytes.
+ */
+import type { ChartExModel } from "./chart-ex-types.js";
+export declare function parseChartEx(rawXml: string): ChartExModel;

package/dist/types/modules/excel/chart/chart-ex-renderer.d.ts

@@ -0,0 +1,187 @@
+/**
+ * ChartEx renderer — serialises a ChartExModel to `cx:chart` XML.
+ *
+ * This is a standalone renderer (not a full SAX parser): it produces byte
+ * output for a programmatically-built chartEx. Round-trip of existing cx:chart
+ * files is handled by raw byte passthrough (model.rawXml is preferred when set).
+ */
+import type { ChartExModel } from "./chart-ex-types.js";
+import { type ChartPdfDrawingSurface, type ChartRenderOptions, type RegionMapDataOptions } from "./chart-renderer.js";
+import { type ChartRect } from "./chart-utils.js";
+/**
+ * Local alias kept for file-level readability. ChartEx code has always
+ * called these `SvgRect`; the underlying shape matches the shared
+ * {@link ChartRect} exactly.
+ */
+type SvgRect = ChartRect;
+/**
+ * Rewrite a freshly-built ChartEx model's data references to use
+ * `_xlchart.vN.M` hidden defined-name indirection, matching the
+ * exact scheme Microsoft Excel emits.
+ *
+ * Excel 2016+ REQUIRES chartEx `<cx:f>` elements to point at
+ * hidden defined names, NOT directly at worksheet ranges. A
+ * chartEx with a bare `<cx:f>Sheet1!$A$1:$A$3</cx:f>` is rejected
+ * on load with:
+ *
+ *   "Removed Part: /xl/drawings/drawingN.xml (Drawing shape)"
+ *
+ * The canonical layout Excel uses:
+ *
+ *   chartEx1.xml:
+ *     <cx:strDim type="cat"><cx:f>_xlchart.v1.0</cx:f></cx:strDim>
+ *     <cx:numDim type="val"><cx:f>_xlchart.v1.1</cx:f></cx:numDim>
+ *
+ *   workbook.xml:
+ *     <definedName name="_xlchart.v1.0" hidden="1">Sheet1!$A$1:$A$3</definedName>
+ *     <definedName name="_xlchart.v1.1" hidden="1">Sheet1!$B$1:$B$3</definedName>
+ *
+ * This function walks the chart's data entries, allocates a
+ * sequential minor index `M` for every worksheet-range formula,
+ * registers a hidden defined name via the supplied callback, and
+ * rewrites the `formula` field on the model to point at the
+ * name. It also clears any cached `<cx:lvl>` point levels on
+ * those dimensions — Excel's output uses defined-name pointers
+ * exclusively; the cached-point form is what our earlier writer
+ * emitted to work around the (buggy) direct-reference path and is
+ * no longer needed.
+ *
+ * Non-worksheet formulas (lambda expressions, literal data,
+ * already-indirect `_xlchart.*` names from round-tripped files)
+ * are left untouched — only `SheetName!...` style references need
+ * the rewrite.
+ *
+ * @param model         ChartEx model to mutate in place.
+ * @param chartExIndex  1-based chartEx file index — becomes the
+ *                      `vN` major version in `_xlchart.vN.M`.
+ * @param register      Callback invoked for each newly allocated
+ *                      defined name. Implementations should add
+ *                      the name to the workbook's `definedNames`
+ *                      list with `hidden="1"`.
+ */
+export declare function rewriteChartExDataRefsToDefinedNames(model: ChartExModel, chartExIndex: number, register: (definedName: string, ref: string) => void): void;
+/**
+ * Render a ChartExModel to the full XML string representation of cx:chart.
+ *
+ * By default the function prefers the raw XML captured at parse time
+ * (`model.rawXml`) when present — that path gives byte-perfect
+ * round-trip for files that haven't been mutated since load. This is
+ * the fastest and safest mode for the common "load → save" pipeline.
+ *
+ * Pass `{ forceStructural: true }` when the caller has mutated
+ * structured fields on the model (e.g. via `setSpPrFill` /
+ * `setSpPrLine` / direct assignment) and needs the writer to
+ * rebuild from the model tree instead of reusing the stale raw bytes.
+ * The `Chart.mutateChartEx` API already clears `model.rawXml` for
+ * normal mutations; `forceStructural` is the escape hatch for callers
+ * that bypass that helper (e.g. low-level tests, ad-hoc scripts).
+ */
+export declare function renderChartEx(model: ChartExModel, options?: {
+    forceStructural?: boolean;
+}): string;
+export declare function renderChartExSvg(model: ChartExModel, options?: ChartRenderOptions): string;
+export declare function renderChartExPng(model: ChartExModel, options?: ChartRenderOptions): Promise<Uint8Array>;
+/**
+ * Layout IDs whose PDF geometry is expressed in `drawRect` /
+ * `drawPath` primitives rather than SVG-specific filters or raster
+ * fallbacks. {@link drawChartExPdf} consults this set to decide
+ * whether a vector path is available; any layout not listed falls
+ * back to the raster pipeline in `chartToPdf`.
+ *
+ * As of the regionMap port this set covers every ChartEx layout the
+ * library currently emits, so vector is the default and raster is
+ * only reached when the caller passes `chartToPdf(chart, {
+ * forceRaster: true })`.
+ *
+ * Exported so the `@pdf/excel-bridge` `chartToPdf` helper can make
+ * the same decision without reimplementing it.
+ */
+export declare const VECTOR_PDF_CHART_EX_LAYOUT_IDS: readonly string[];
+/**
+ * True when every series of a ChartEx model has a layoutId that
+ * `drawChartExPdf` can render as vector PDF. Used by `chartToPdf` to
+ * route the chart to the vector or raster path automatically.
+ */
+export declare function canRenderChartExAsVectorPdf(model: ChartExModel): boolean;
+/**
+ * Draw a ChartEx chart as vector content onto a
+ * {@link ChartPdfDrawingSurface}. All layout IDs listed in
+ * {@link VECTOR_PDF_CHART_EX_LAYOUT_IDS} are supported — the
+ * surrounding geometry lives in the "collect" functions shared with
+ * the SVG renderer, so the SVG and PDF paths stay equivalent by
+ * construction.
+ *
+ * For any layout ID not in the set the function throws; callers
+ * (notably `@pdf/excel-bridge.chartToPdf`) must pre-filter via
+ * {@link canRenderChartExAsVectorPdf}. Filtering ahead of time rather
+ * than silently skipping preserves "fail loud on unsupported" — a
+ * silent no-op would produce an empty page and hide the mistake.
+ */
+export declare function drawChartExPdf(surface: ChartPdfDrawingSurface, model: ChartExModel, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, options?: {
+    title?: string;
+    regionMap?: RegionMapDataOptions;
+}): ChartPdfDrawingSurface;
+interface HierarchyNode {
+    name: string;
+    value: number;
+    children: HierarchyNode[];
+}
+/**
+ * Treemap geometry collector. Shared between the SVG emitter (which
+ * prints `<rect>` elements) and the PDF emitter (which calls
+ * `surface.drawRect` / `surface.drawText`). Returning plain data —
+ * rect, colour, optional label — keeps both backends honest: any
+ * future visual regression in the geometry shows up on the test that
+ * exercises the primary (SVG) backend, not only on the secondary
+ * (PDF) one.
+ *
+ * The label threshold (> 40 × 18 pixels) mirrors the historical SVG
+ * code; both backends honour it identically so small treemap cells
+ * degrade to colour-only the same way everywhere.
+ */
+export interface TreemapCell {
+    rect: SvgRect;
+    color: string;
+    label: string | undefined;
+}
+export declare function collectTreemapCells(root: HierarchyNode, plot: SvgRect): TreemapCell[];
+/**
+ * Sunburst geometry collector. Recursively walks the hierarchy,
+ * emitting one {@link SunburstSlice} per non-root node in the same
+ * angular/ring order the SVG renderer has always used, so the two
+ * backends stay pixel-equivalent modulo rasterisation.
+ *
+ * Colour handling follows the original `renderSunburstNode`
+ * "increment on every visit" rule so sibling slices and their
+ * descendants walk through `COLORS` in the same sequence regardless of
+ * which backend is driving.
+ */
+export interface SunburstSlice {
+    cx: number;
+    cy: number;
+    /** Outer ring radius, always >= `inner`. */
+    outer: number;
+    /** Inner ring radius; 0 for the innermost ring. */
+    inner: number;
+    /** Start angle in radians, 0 = +X axis. */
+    start: number;
+    /** End angle in radians. */
+    end: number;
+    color: string;
+}
+export declare function collectSunburstSlices(root: HierarchyNode, plot: SvgRect): SunburstSlice[];
+/**
+ * Serialise a `cx:legend` element to XML. Exported so the xlsx raw-
+ * patch path (`buildRawChartExLegendXml` in `xlsx.browser.ts`) can
+ * produce identical output to the structured writer. Previously the
+ * raw patcher emitted a self-closing `<cx:legend pos="…"/>`, dropping
+ * `align`, `cx:legendEntry*`, `cx:spPr`, `cx:txPr`, and `cx:extLst`
+ * on every styled-legend round-trip.
+ */
+export declare function renderChartExLegendXml(l: NonNullable<ChartExModel["chartSpace"]["chart"]["legend"]>): string;
+export {};