@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/browser/modules/excel/defined-names.js

@@ -218,6 +218,7 @@ class DefinedNames {
         this.matrixMap = {};
         this.formulaMap = {};
         this.localSheetIdMap = {};
+        this.hiddenMap = {};
         this.opaqueMap = {};
         this.nameForKey = {};
         this._explicitProbe = probe ?? null;
@@ -239,6 +240,29 @@ class DefinedNames {
         this.nameForKey[name] = name;
         this.addEx(location, name);
     }
+    /**
+     * Register a hidden defined name that maps a chartEx `_xlchart.vN.M`
+     * pointer to a worksheet range. Excel emits one of these for every
+     * data reference in a chartEx chart:
+     *
+     *   <definedName name="_xlchart.v1.0" hidden="1">Sheet1!$A$1:$A$3</definedName>
+     *
+     * The chartEx then references `_xlchart.v1.0` from its `<cx:f>`
+     * element instead of the worksheet range directly. Direct sheet
+     * references in `<cx:f>` are rejected by Excel 2016+ with
+     * "Removed Part: /xl/drawings/drawingN.xml (Drawing shape)" on
+     * load, so chartEx data MUST go through this indirection.
+     *
+     * Same semantics as `add()` but also marks the name `hidden` so
+     * it does not show up in Excel's Name Manager UI.
+     *
+     * @param locStr - Worksheet reference (e.g. `"Sheet1!$A$1:$A$3"`)
+     * @param name   - Defined name to register (e.g. `"_xlchart.v1.0"`)
+     */
+    addHidden(locStr, name) {
+        this.add(locStr, name);
+        this.hiddenMap[name] = true;
+    }
     addEx(location, name) {
         const matrix = this.getMatrix(name);
         if ("top" in location) {
@@ -516,10 +540,15 @@ class DefinedNames {
             .map(([sKey, matrix]) => {
             const result = this.getRanges(sKey, matrix);
             const localSheetId = this.localSheetIdMap[sKey];
+            const hidden = this.hiddenMap[sKey];
+            const out = { ...result };
             if (localSheetId !== undefined) {
-                return { ...result, localSheetId };
+                out.localSheetId = localSheetId;
             }
-            return result;
+            if (hidden) {
+                out.hidden = true;
+            }
+            return out;
         })
             .filter((definedName) => definedName.ranges.length);
         // Formula-based names from formulaMap (only include names not already in matrixMap)
@@ -534,20 +563,27 @@ class DefinedNames {
             };
             const localSheetId = this.localSheetIdMap[sKey];
             if (localSheetId !== undefined) {
-                return { ...result, localSheetId };
+                result.localSheetId = localSheetId;
+            }
+            if (this.hiddenMap[sKey]) {
+                result.hidden = true;
             }
             return result;
         });
         // Opaque names — rawText preserved for round-trip
         const opaqueNames = Object.entries(this.opaqueMap).map(([sKey, entry]) => {
             const bareName = this.nameForKey[sKey] ?? sKey;
-            return {
+            const out = {
                 name: bareName,
                 ranges: [],
                 rawText: entry.rawText,
                 localSheetId: entry.localSheetId,
                 kind: "opaque"
             };
+            if (this.hiddenMap[sKey]) {
+                out.hidden = true;
+            }
+            return out;
         });
         return [...cellNames, ...formulaNames, ...opaqueNames];
     }
@@ -563,6 +599,7 @@ class DefinedNames {
         const matrixMap = (this.matrixMap = {});
         const formulaMap = (this.formulaMap = {});
         const localSheetIdMap = (this.localSheetIdMap = {});
+        const hiddenMap = (this.hiddenMap = {});
         const opaqueMap = (this.opaqueMap = {});
         const nameForKeyMap = (this.nameForKey = {});
         // Resolve probe lazily: a caller may have constructed the Workbook
@@ -577,6 +614,9 @@ class DefinedNames {
             if (definedName.localSheetId !== undefined) {
                 localSheetIdMap[sKey] = definedName.localSheetId;
             }
+            if (definedName.hidden) {
+                hiddenMap[sKey] = true;
+            }
             // Programmatic API path: formulaExpression already set and no rawText
             if (definedName.formulaExpression && definedName.rawText === undefined) {
                 formulaMap[sKey] = definedName.formulaExpression;

package/dist/browser/modules/excel/errors.d.ts

@@ -110,6 +110,12 @@ export declare class ExcelDownloadError extends ExcelError {
 export declare class PivotTableError extends ExcelError {
     name: string;
 }
+/**
+ * Error thrown when chart configuration is invalid.
+ */
+export declare class ChartOptionsError extends ExcelError {
+    name: string;
+}
 /**
  * Error thrown when table configuration or operation is invalid.
  */

package/dist/browser/modules/excel/errors.js

@@ -145,6 +145,15 @@ export class PivotTableError extends ExcelError {
         this.name = "PivotTableError";
     }
 }
+/**
+ * Error thrown when chart configuration is invalid.
+ */
+export class ChartOptionsError extends ExcelError {
+    constructor() {
+        super(...arguments);
+        this.name = "ChartOptionsError";
+    }
+}
 /**
  * Error thrown when table configuration or operation is invalid.
  */

package/dist/browser/modules/excel/form-control.d.ts

@@ -97,6 +97,12 @@ declare class FormCheckbox {
     worksheet: Worksheet;
     model: FormCheckboxModel;
     constructor(worksheet: Worksheet, range: FormControlRange, options?: FormCheckboxOptions);
+    /**
+     * Rebuild a FormCheckbox from a previously-serialised model (e.g. round-tripped
+     * via `worksheet.model`). The model is adopted as-is; no range parsing or shape
+     * id reassignment is performed.
+     */
+    static fromModel(worksheet: Worksheet, model: FormCheckboxModel): FormCheckbox;
     /**
      * Get the checked state
      */

package/dist/browser/modules/excel/form-control.js

@@ -51,6 +51,23 @@ class FormCheckbox {
             print: options?.print ?? false
         };
     }
+    /**
+     * Rebuild a FormCheckbox from a previously-serialised model (e.g. round-tripped
+     * via `worksheet.model`). The model is adopted as-is; no range parsing or shape
+     * id reassignment is performed.
+     */
+    static fromModel(worksheet, model) {
+        const cb = Object.create(FormCheckbox.prototype);
+        cb.worksheet = worksheet;
+        // Defensive shallow clone: the caller should not be able to mutate the
+        // underlying anchor objects through the original reference.
+        cb.model = {
+            ...model,
+            tl: { ...model.tl },
+            br: { ...model.br }
+        };
+        return cb;
+    }
     /**
      * Get the checked state
      */

package/dist/browser/modules/excel/image.js

@@ -92,9 +92,19 @@ class Image {
                 };
             }
             else if (range) {
+                // Anchor inputs:
+                //   - string addresses ("A1") are 1-based; the internal Anchor uses
+                //     0-based nativeCol/nativeRow, so the top-left address is shifted
+                //     by -1. The bottom-right address is intentionally NOT shifted —
+                //     this matches the string-range path (e.g. "A1:B2") where br
+                //     anchors the cell *past* the address (i.e. its right/bottom edge).
+                //   - object inputs ({ col, row } / AnchorModel) already use the
+                //     0-based convention and are passed through as-is.
+                const tlInput = range.tl;
+                const brInput = range.br;
                 this.range = {
-                    tl: new Anchor(this.worksheet, range.tl, 0),
-                    br: range.br ? new Anchor(this.worksheet, range.br, 0) : undefined,
+                    tl: new Anchor(this.worksheet, tlInput, typeof tlInput === "string" ? -1 : 0),
+                    br: brInput ? new Anchor(this.worksheet, brInput, 0) : undefined,
                     ext: range.ext,
                     editAs: range.editAs,
                     hyperlinks: hyperlinks || ("hyperlinks" in range ? range.hyperlinks : undefined)

package/dist/browser/modules/excel/pivot-chart.d.ts

@@ -0,0 +1,7 @@
+import type { AddChartOptions, AddComboChartOptions, PivotChartOptions as PivotChartMetadataOptions, PivotChartSource } from "./chart/types.js";
+import type { PivotTable } from "./pivot-table.js";
+type PivotChartCreationOptions = AddChartOptions | AddComboChartOptions;
+export declare function withPivotChartSource<T extends PivotChartCreationOptions>(pivotTable: PivotTable, options: T, fmtId?: number, pivotChartOptions?: PivotChartMetadataOptions): T & {
+    pivotSource: PivotChartSource;
+};
+export {};

package/dist/browser/modules/excel/pivot-chart.js

@@ -0,0 +1,53 @@
+import { quoteSheetName } from "./utils/address.js";
+const DEFAULT_PIVOT_CHART_PIVOT_AREA_XML = '<pivotArea type="data" outline="0" fieldPosition="0"><references count="1"><reference field="4294967294" count="1" selected="0"><x v="0"/></reference></references></pivotArea>';
+export function withPivotChartSource(pivotTable, options, fmtId, pivotChartOptions) {
+    // Auto-assign the next available fmtId when the caller didn't pass
+    // one. Before this fix, a second `addPivotChart(pivotTable, …)`
+    // against the same pivot would reuse `fmtId=0`, collide with the
+    // first chart's `chartFormat` entry (the `exists` guard in
+    // `ensurePivotChartFormat` would no-op), and produce two charts
+    // pointing at a single pivotArea declaration — Excel renders only
+    // one of them correctly.
+    const existingFormats = pivotTable.chartFormats ?? [];
+    const allocatedFmtId = fmtId ??
+        (existingFormats.length === 0 ? 0 : Math.max(...existingFormats.map(f => f.format ?? 0)) + 1);
+    const resolvedPivotOpts = pivotChartOptions ?? options.pivotChartOptions;
+    ensurePivotChartFormat(pivotTable, allocatedFmtId);
+    applyPivotChartOptions(pivotTable, resolvedPivotOpts);
+    return {
+        ...options,
+        pivotSource: {
+            name: buildPivotChartSourceName(pivotTable),
+            fmtId: allocatedFmtId,
+            options: resolvedPivotOpts
+        }
+    };
+}
+function applyPivotChartOptions(pivotTable, options) {
+    if (!options) {
+        return;
+    }
+    pivotTable.pivotChartOptions = options;
+    if (options.refreshOnOpen && pivotTable.cacheDefinition) {
+        pivotTable.cacheDefinition.refreshOnLoad = "1";
+    }
+}
+function ensurePivotChartFormat(pivotTable, fmtId) {
+    pivotTable.chartFormat ?? (pivotTable.chartFormat = 1);
+    pivotTable.chartFormats ?? (pivotTable.chartFormats = []);
+    const exists = pivotTable.chartFormats.some(format => format.chart === 0 && format.format === fmtId);
+    if (!exists) {
+        pivotTable.chartFormats.push({
+            chart: 0,
+            format: fmtId,
+            series: true,
+            pivotAreaXml: DEFAULT_PIVOT_CHART_PIVOT_AREA_XML
+        });
+    }
+}
+function buildPivotChartSourceName(pivotTable) {
+    const tableName = pivotTable.name ?? `PivotTable${pivotTable.tableNumber}`;
+    return pivotTable.worksheetName
+        ? `${quoteSheetName(pivotTable.worksheetName)}!${tableName}`
+        : tableName;
+}

package/dist/browser/modules/excel/pivot-table.d.ts

@@ -1,3 +1,4 @@
+import type { PivotChartOptions } from "./chart/types.js";
 import type { Table } from "./table.js";
 /**
  * Interface representing the source data abstraction for pivot tables.
@@ -117,6 +118,28 @@ export interface PivotTableModel {
      * @default '1'
      */
     applyWidthHeightFormats?: "0" | "1";
+    /**
+     * Top-left cell anchor for the pivot table, e.g. `"A3"` or `"E5"`.
+     *
+     * Specifies where the pivot's displayed block begins. When page filters are
+     * present they occupy rows from the anchor downward, followed by a blank
+     * separator row and then the pivot body (header + data). The library sizes
+     * the initial placeholder range automatically — when Excel refreshes the
+     * pivot cache it expands the pivot from this anchor to its full size.
+     *
+     * When multiple pivot tables share a worksheet, each must be given a distinct
+     * anchor with enough vertical or horizontal room between them so the expanded
+     * pivots do not overlap. Excel reports "there's already a PivotTable there"
+     * when refreshing two overlapping pivots, so this option is required for
+     * dashboards that host several pivots on one sheet.
+     *
+     * Accepts a single-cell address (`"A3"`). A range reference (`"A3:C5"`) is
+     * also tolerated — only the top-left cell is used; the range extent is
+     * recomputed from the pivot's field layout.
+     *
+     * @default `"A3"` (row 3 of column A)
+     */
+    ref?: string;
 }
 /** Allowed element types within CacheField.sharedItems */
 export type SharedItemValue = string | number | boolean | Date | PivotErrorValue | null;
@@ -193,11 +216,28 @@ export interface DataField {
     /** Number format ID (preserved on roundtrip for currency/date formatting) */
     numFmtId?: number;
 }
+/**
+ * A pivot table chart format entry used by pivot charts.
+ */
+export interface PivotTableChartFormat {
+    /** Chart index within the pivot chart formatting collection. */
+    chart: number;
+    /** Format ID referenced by c:pivotSource/c:fmtId. */
+    format: number;
+    /** Whether this format applies to a series. */
+    series?: boolean;
+    /** Preserved or generated pivotArea XML. */
+    pivotAreaXml?: string;
+}
 /**
  * Internal pivot table representation used by the library.
  * This is the processed model after calling makePivotTable().
  */
 export interface PivotTable {
+    /** Pivot table display name, defaults to `PivotTable${tableNumber}` for new tables. */
+    name?: string;
+    /** Worksheet containing the pivot table. */
+    worksheetName?: string;
     /** Source data adapter (always present for new pivot tables) */
     source?: PivotTableSource;
     /** Field indices for row fields */
@@ -218,6 +258,14 @@ export interface PivotTable {
     cacheId: string;
     /** Width/height format setting */
     applyWidthHeightFormats: "0" | "1";
+    /**
+     * Top-left cell anchor for the pivot block (e.g. `"A3"`).
+     * When present, overrides the default `A{3+pageOffset}` anchor used by the
+     * writer. The anchor represents the cell where the pivot's displayed area
+     * starts (page filters if any, followed by a blank row, followed by the
+     * pivot body).
+     */
+    ref?: string;
     /** 1-indexed table number for file naming (pivotTable1.xml, pivotTable2.xml, etc.) */
     tableNumber: number;
     /** Workbook relationship ID, assigned during write by addWorkbookRels() */
@@ -230,6 +278,12 @@ export interface PivotTable {
     cacheDefinition?: ParsedCacheDefinition;
     /** Cache records for loaded pivot tables */
     cacheRecords?: ParsedCacheRecords;
+    /** Root chartFormat attribute used by pivot charts. */
+    chartFormat?: number;
+    /** Chart format entries used by pivot charts. */
+    chartFormats?: PivotTableChartFormat[];
+    /** Structured pivot chart metadata attached by addPivotChart/addPivotChartsheet. */
+    pivotChartOptions?: PivotChartOptions;
 }
 /**
  * Parsed cache definition from loaded pivot table files.
@@ -299,5 +353,6 @@ declare function makePivotTable(worksheet: {
     workbook: {
         pivotTables: PivotTable[];
     };
+    name: string;
 }, model: PivotTableModel): PivotTable;
 export { makePivotTable };

package/dist/browser/modules/excel/pivot-table.js

@@ -183,8 +183,14 @@ function makePivotTable(worksheet, model) {
     const nextCacheId = existingCacheIds.length > 0
         ? existingCacheIds.reduce((a, b) => (a > b ? a : b), -Infinity) + 1
         : BASE_CACHE_ID + tableNumber - 1;
+    // Normalise the optional user-supplied anchor. A range (e.g. "A3:C5") is
+    // reduced to its top-left cell; the pivot's own field layout determines the
+    // extent of the placeholder location written to XML.
+    const ref = normalisePivotRef(model.ref);
     // form pivot table object
     return {
+        name: `PivotTable${tableNumber}`,
+        worksheetName: worksheet.name,
         source,
         rows: rowIndices,
         columns: columnIndices,
@@ -198,10 +204,39 @@ function makePivotTable(worksheet, model) {
         // '0' = preserve worksheet column widths (useful for custom sizing)
         // '1' = apply pivot table style width/height (default Excel behavior)
         applyWidthHeightFormats: model.applyWidthHeightFormats ?? "1",
+        ref,
         // Table number for file naming (pivotTable1.xml, pivotTable2.xml, etc.)
         tableNumber
     };
 }
+/**
+ * Normalise a user-supplied pivot anchor to a canonical top-left cell address
+ * (e.g. `"A3"`). Accepts either a single cell or a range; ranges are collapsed
+ * to their top-left cell. Returns `undefined` when the input is missing.
+ */
+function normalisePivotRef(ref) {
+    if (ref === undefined) {
+        return undefined;
+    }
+    if (typeof ref !== "string" || ref.trim() === "") {
+        throw new PivotTableError(`Invalid pivot table ref "${String(ref)}". Provide a cell address like "A3".`);
+    }
+    // Strip an optional sheet prefix ("Sheet1!A3") so users can pass through
+    // range strings composed elsewhere without surprises.
+    const trimmed = ref.trim().replace(/^[^!]+!/, "");
+    const topLeft = trimmed.includes(":") ? trimmed.split(":", 1)[0] : trimmed;
+    let decoded;
+    try {
+        decoded = colCache.decodeAddress(topLeft);
+    }
+    catch {
+        throw new PivotTableError(`Invalid pivot table ref "${ref}". Provide a cell address like "A3".`);
+    }
+    if (!decoded.col || !decoded.row) {
+        throw new PivotTableError(`Invalid pivot table ref "${ref}". Both column and row are required (e.g. "A3").`);
+    }
+    return `${colCache.n2l(decoded.col)}${decoded.row}`;
+}
 function validate(model, source) {
     const columns = model.columns ?? [];
     const pages = model.pages ?? [];

package/dist/browser/modules/excel/range.js

@@ -170,10 +170,14 @@ class Range {
     get _serialisedSheetName() {
         const { sheetName } = this.model;
         if (sheetName) {
+            // Plain ASCII identifiers (and the empty string) need no quoting.
             if (/^[a-zA-Z0-9]*$/.test(sheetName)) {
                 return `${sheetName}!`;
             }
-            return `'${sheetName}'!`;
+            // Per OOXML / Excel formula syntax, sheet names containing characters
+            // outside the bareword set are wrapped in single quotes, and any
+            // embedded apostrophes are doubled (e.g. `O'Brien` -> `'O''Brien'`).
+            return `'${sheetName.replace(/'/g, "''")}'!`;
         }
         return "";
     }

package/dist/browser/modules/excel/sparkline/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Sparkline module — worksheet mini-charts.
+ *
+ * Sparklines are rendered as `x14:sparklineGroups` inside the worksheet's
+ * extLst. They are distinct from chart objects (which live in chartN.xml).
+ */
+export * from "./sparkline.js";

package/dist/browser/modules/excel/sparkline/index.js

@@ -0,0 +1,7 @@
+/**
+ * Sparkline module — worksheet mini-charts.
+ *
+ * Sparklines are rendered as `x14:sparklineGroups` inside the worksheet's
+ * extLst. They are distinct from chart objects (which live in chartN.xml).
+ */
+export * from "./sparkline.js";

package/dist/browser/modules/excel/sparkline/sparkline.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Sparkline (mini chart) data model and utilities.
+ *
+ * Sparklines are cell-sized charts stored in the worksheet extLst under
+ * `x14:sparklineGroups`. Each group contains:
+ *   - display options (type, line weight, markers, axis settings, colors)
+ *   - one or more sparklines, each pairing a data reference with an anchor cell.
+ *
+ * Reference: ECMA-376 §18.18.92 + Office Open XML extension `x14` namespace.
+ */
+/**
+ * Top-level sparkline group — matches `x14:sparklineGroup`.
+ */
+export interface SparklineGroup {
+    /** Chart type: line | column | stacked (win-loss) */
+    type?: SparklineType;
+    /** Line weight in points (0.25 - 2.25) */
+    lineWeight?: number;
+    /** Display empty cells as: gap, zero, or span */
+    displayEmptyCellsAs?: "gap" | "zero" | "span";
+    /** Whether to display markers */
+    markers?: boolean;
+    /** High point marker */
+    high?: boolean;
+    /** Low point marker */
+    low?: boolean;
+    /** First point marker */
+    first?: boolean;
+    /** Last point marker */
+    last?: boolean;
+    /** Negative point marker */
+    negative?: boolean;
+    /** Display X axis */
+    displayXAxis?: boolean;
+    /** Display hidden cells data */
+    displayHidden?: boolean;
+    /** Min axis type: individual, group, custom */
+    minAxisType?: SparklineAxisType;
+    /** Max axis type */
+    maxAxisType?: SparklineAxisType;
+    /** Manual min (when minAxisType === "custom") */
+    manualMin?: number;
+    /** Manual max (when maxAxisType === "custom") */
+    manualMax?: number;
+    /** Right-to-left */
+    rightToLeft?: boolean;
+    /** Color series */
+    colorSeries?: SparklineColor;
+    /** Color negative */
+    colorNegative?: SparklineColor;
+    /** Color axis */
+    colorAxis?: SparklineColor;
+    /** Color markers */
+    colorMarkers?: SparklineColor;
+    /** Color first */
+    colorFirst?: SparklineColor;
+    /** Color last */
+    colorLast?: SparklineColor;
+    /** Color high */
+    colorHigh?: SparklineColor;
+    /** Color low */
+    colorLow?: SparklineColor;
+    /** Date axis source (reference range of dates) */
+    dateAxis?: string;
+    /** Sparklines in this group */
+    sparklines: Sparkline[];
+}
+export type SparklineType = "line" | "column" | "stacked";
+export type SparklineAxisType = "individual" | "group" | "custom";
+/**
+ * A single sparkline within a group.
+ */
+export interface Sparkline {
+    /** Data reference (e.g. "Sheet1!B2:G2") */
+    dataRef: string;
+    /** Anchor cell reference (e.g. "H2") */
+    cellRef: string;
+}
+/**
+ * Sparkline color — theme reference or sRGB.
+ */
+export interface SparklineColor {
+    /** Theme index (0-11) */
+    theme?: number;
+    /** sRGB hex */
+    rgb?: string;
+    /** Tint (-1 to 1) */
+    tint?: number;
+    /** Auto color */
+    auto?: boolean;
+}
+/**
+ * High-level options for creating a sparkline group.
+ */
+export interface AddSparklineGroupOptions {
+    /** Chart type */
+    type: SparklineType;
+    /** List of sparklines (data + anchor) */
+    sparklines: Sparkline[];
+    /** Line weight in points */
+    lineWeight?: number;
+    /** Show markers (line type) */
+    markers?: boolean;
+    /** Show high point */
+    high?: boolean;
+    /** Show low point */
+    low?: boolean;
+    /** Show first point */
+    first?: boolean;
+    /** Show last point */
+    last?: boolean;
+    /** Show negative points */
+    negative?: boolean;
+    /** Line color */
+    lineColor?: string;
+    /** Negative bar color */
+    negativeColor?: string;
+    /**
+     * Colour for the reference line drawn when {@link displayXAxis} is
+     * enabled. Maps to `<x14:colorAxis>` — the horizontal rule that
+     * separates positive from negative values on a sparkline.
+     */
+    axisColor?: string;
+    /**
+     * Colour applied to ordinary marker dots (those that are neither
+     * first/last/high/low/negative). Maps to `<x14:colorMarkers>`.
+     */
+    markerColor?: string;
+    /** High marker color */
+    highColor?: string;
+    /** Low marker color */
+    lowColor?: string;
+    /** First marker color */
+    firstColor?: string;
+    /** Last marker color */
+    lastColor?: string;
+    /** Min axis type */
+    minAxisType?: SparklineAxisType;
+    /** Max axis type */
+    maxAxisType?: SparklineAxisType;
+    /** Manual min */
+    manualMin?: number;
+    /** Manual max */
+    manualMax?: number;
+    /** Show X axis */
+    displayXAxis?: boolean;
+    /** Right-to-left */
+    rightToLeft?: boolean;
+    /** Display empty cells as */
+    displayEmptyCellsAs?: "gap" | "zero" | "span";
+    /** Date axis source */
+    dateAxis?: string;
+}
+/**
+ * Build a SparklineGroup from simplified options.
+ */
+export declare function buildSparklineGroup(opts: AddSparklineGroupOptions): SparklineGroup;
+/**
+ * Render all sparkline groups on a worksheet to an x14:sparklineGroups
+ * XML fragment. Returns a string (empty if no groups).
+ */
+export declare function renderSparklineGroups(groups: SparklineGroup[]): string;
+/**
+ * Parse an x14:sparklineGroups XML fragment into structured groups.
+ * Best-effort regex-based parser — sufficient for round-trip via rebuild.
+ */
+export declare function parseSparklineGroups(xml: string): SparklineGroup[];
+/**
+ * Options for {@link renderSparklineSvg}.
+ */
+export interface SparklineRenderOptions {
+    /** Output width in px (default 120). */
+    width?: number;
+    /** Output height in px (default 30). */
+    height?: number;
+    /** Background fill colour. When absent, the SVG has a transparent background. */
+    background?: string;
+    /** Inner padding in px so markers don't clip against the SVG edges. */
+    padding?: number;
+}
+/**
+ * Render a sparkline group to a single SVG string given explicit data
+ * values for each sparkline in the group. This is a preview-grade
+ * renderer suitable for PDF/PNG embedding — Excel ultimately renders
+ * sparklines natively from the formula references.
+ *
+ * Why take `values: number[][]` rather than walk the workbook: the
+ * caller already has a worksheet in scope when it wants a preview,
+ * and decoupling the renderer from the worksheet keeps this module
+ * free of upstream dependencies. When no per-sparkline data is
+ * supplied the SVG is rendered empty (just the background) so the
+ * function never throws.
+ *
+ * Respects the group's `type` (`line` / `column` / `stacked`),
+ * `displayXAxis`, `minAxisType` / `maxAxisType` / `manualMin` /
+ * `manualMax`, markers (`markers`, `first`, `last`, `high`, `low`,
+ * `negative`), `rightToLeft`, and all structural colours
+ * (`colorSeries`, `colorNegative`, `colorAxis`, `colorMarkers`,
+ * `colorHigh`, `colorLow`, `colorFirst`, `colorLast`).
+ *
+ * The individual sparkline's `cellRef` is not consulted — the caller
+ * controls layout at a higher level and this function returns a
+ * standalone SVG per sparkline when passed a group with a single
+ * member, or a grid-stacked SVG when given multiple members.
+ */
+export declare function renderSparklineSvg(group: SparklineGroup, values: number[][], options?: SparklineRenderOptions): string;