@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/types/modules/excel/chart-host-registry.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Chart Support Registry
+ *
+ * A tiny indirection layer that lets `Worksheet`, `Workbook` and
+ * `Chartsheet` call into chart-building, chart-rendering and chart
+ * cache-population code **only if the host application has opted in**
+ * by calling `installChartSupport()` from
+ * `@cj-tech-master/excelts/chart`.
+ *
+ * ## Why a registry
+ *
+ * The chart module ships 17 files covering classic charts, ChartEx
+ * (Excel 2016+), SVG/PNG/PDF renderers, preset catalogues, shape
+ * properties, TopoJSON region maps and cache populators — roughly
+ * 30,000 lines of TypeScript. Empirical measurement shows that making
+ * `Worksheet` import from chart directly forces ~1.2 MB of chart code
+ * into every consumer bundle, even for consumers who only read and
+ * write cells.
+ *
+ * This file is the single point of indirection. Importing `Worksheet`
+ * pulls it in (~1 KB) but does NOT pull in the chart implementation;
+ * the implementation only arrives once someone calls
+ * `installChartSupport()`, which bundlers resolve to the
+ * `@cj-tech-master/excelts/chart` subpath import graph.
+ *
+ * If chart-manipulating APIs (`worksheet.addChart()`, `workbook.writeFile()`
+ * with charts, etc.) are called without `installChartSupport()` having
+ * run, a clear error is thrown telling the developer how to fix it.
+ *
+ * ## Why it lives in `excel/` rather than `excel/chart/`
+ *
+ * Host-registry pattern convention: the slot lives with the consumer,
+ * not with the provider. `worksheet.ts`, `workbook.browser.ts` and
+ * `chartsheet.ts` are the consumers and they all live in `excel/`, so
+ * the slot sits next to them. The chart module only depends on it when
+ * `install()` is called — a one-way arrow from provider to consumer.
+ *
+ * This differs from `@formula/host-registry` which lives inside the
+ * formula module because formula is a separate top-level module (layer
+ * 3) that cannot import from excel. Chart is nested under excel
+ * (layer 4), so the slot naturally lives in excel.
+ *
+ * ## Relationship to formula's host-registry
+ *
+ * The two registries are independent slots for independent optional
+ * features. A consumer may install chart without formula, formula
+ * without chart, both, or neither.
+ */
+import type { fillChartCaches, fillChartExCaches } from "./chart/cache-populator.js";
+import type { Chart, ChartAnchorModel, buildChartModel } from "./chart/chart.js";
+import type { chartExOptionsFromRows, chartExOptionsFromTable, chartOptionsFromRows, chartOptionsFromTable, seriesFromColumns } from "./chart/chart-api.js";
+import type { buildComboChartModel } from "./chart/chart-builder.js";
+import type { buildChartExModel } from "./chart/chart-ex-builder.js";
+import type { parseChartEx } from "./chart/chart-ex-parser.js";
+import type { canRenderChartExAsVectorPdf, drawChartExPdf, renderChartEx, renderChartExLegendXml, renderChartExPng, rewriteChartExDataRefsToDefinedNames } from "./chart/chart-ex-renderer.js";
+import type { resolvePendingChartImages } from "./chart/chart-images.js";
+import type { applyChartExPreset, applyChartPreset } from "./chart/chart-presets.js";
+import type { drawChartPdf, renderChartPng } from "./chart/chart-renderer.js";
+import type { buildChartColors, buildChartStyle } from "./chart/chart-sidecar.js";
+import type { themeIndexToName } from "./chart/chart-utils.js";
+import type { AddChartRange } from "./chart/types.js";
+import type { Worksheet } from "./worksheet.js";
+import type { ChartSpaceXform } from "./xlsx/xform/chart/chart-space-xform.js";
+/**
+ * Runtime chart functions the excel module needs from the chart
+ * module. Populated by `installChartSupport()` from
+ * `@cj-tech-master/excelts/chart`.
+ *
+ * Using `typeof <fn>` keeps the signatures in lockstep with the real
+ * implementations — add an argument to `buildChartModel` and this
+ * interface updates automatically, as do all call sites. Consumers who
+ * provide a custom chart-support implementation (test doubles, mock
+ * providers) get a type error when signatures drift.
+ *
+ * The `Chart` class constructor is wrapped in a factory function
+ * (`createChart`) rather than exposed as a raw constructor reference:
+ * `new (getChartSupport().Chart)(...)` reads poorly at the call site,
+ * `getChartSupport().createChart(...)` reads cleanly.
+ */
+export interface ChartSupport {
+    readonly buildChartModel: typeof buildChartModel;
+    readonly buildComboChartModel: typeof buildComboChartModel;
+    readonly buildChartExModel: typeof buildChartExModel;
+    readonly applyChartPreset: typeof applyChartPreset;
+    readonly applyChartExPreset: typeof applyChartExPreset;
+    readonly fillChartCaches: typeof fillChartCaches;
+    readonly fillChartExCaches: typeof fillChartExCaches;
+    readonly resolvePendingChartImages: typeof resolvePendingChartImages;
+    readonly buildChartStyle: typeof buildChartStyle;
+    readonly buildChartColors: typeof buildChartColors;
+    /**
+     * Factory for a `Chart` instance. Preferred over exposing the raw
+     * constructor because `new (getChartSupport().Chart)(...)` is
+     * awkward at call sites.
+     *
+     * Accepts either an `AddChartRange` (the public addChart API
+     * surface: A1-notation strings, tl/br pairs, tl+ext, or pos+ext)
+     * **or** a `ChartAnchorModel["range"]` (the model-shaped form
+     * re-hydrated from an XLSX drawing anchor). The Chart constructor
+     * accepts both and routes through the same `parseRange` helper.
+     */
+    readonly createChart: (worksheet: Worksheet, ids: {
+        chartNumber?: number;
+        chartExNumber?: number;
+    }, range: AddChartRange | ChartAnchorModel["range"]) => Chart;
+    readonly chartOptionsFromTable: typeof chartOptionsFromTable;
+    readonly chartOptionsFromRows: typeof chartOptionsFromRows;
+    readonly chartExOptionsFromTable: typeof chartExOptionsFromTable;
+    readonly chartExOptionsFromRows: typeof chartExOptionsFromRows;
+    readonly seriesFromColumns: typeof seriesFromColumns;
+    readonly parseChartEx: typeof parseChartEx;
+    readonly renderChartEx: typeof renderChartEx;
+    readonly renderChartExLegendXml: typeof renderChartExLegendXml;
+    readonly rewriteChartExDataRefsToDefinedNames: typeof rewriteChartExDataRefsToDefinedNames;
+    readonly themeIndexToName: typeof themeIndexToName;
+    /**
+     * Factory for the classic-chart XLSX xform (`c:chartSpace` parser +
+     * writer). `chart-space-xform.ts` itself statically imports
+     * `chart-utils` and `shape-properties` from the chart module, so
+     * exposing it through the registry ensures a consumer who never
+     * installs chart support also never pulls those chart files into
+     * their bundle via the xform graph.
+     */
+    readonly createChartSpaceXform: () => ChartSpaceXform;
+    readonly drawChartPdf: typeof drawChartPdf;
+    readonly drawChartExPdf: typeof drawChartExPdf;
+    readonly renderChartPng: typeof renderChartPng;
+    readonly renderChartExPng: typeof renderChartExPng;
+    readonly canRenderChartExAsVectorPdf: typeof canRenderChartExAsVectorPdf;
+}
+/**
+ * Install a chart runtime implementation. Called from
+ * `installChartSupport()` in the `@cj-tech-master/excelts/chart`
+ * subpath.
+ *
+ * Re-installing is allowed — the last registration wins. Passing
+ * `null` uninstalls chart support, which is useful for tests that
+ * exercise the "no chart" error path.
+ */
+export declare function registerChartSupport(support: ChartSupport | null): void;
+/** Returns true when chart support has been installed. */
+export declare function hasChartSupport(): boolean;
+/**
+ * Retrieve the installed chart support. Throws a descriptive error if
+ * no chart support is installed.
+ */
+export declare function getChartSupport(): ChartSupport;
+/**
+ * Retrieve installed chart support, or `null` if none is installed.
+ *
+ * Used by code paths that can gracefully degrade when chart support is
+ * missing — e.g. ChartEx loading, which can preserve raw XML verbatim
+ * without a full parse when chart support is absent. Note that classic
+ * chart loading currently requires chart support to be installed (the
+ * reader calls `getChartSupport()` unconditionally for classic charts).
+ */
+export declare function tryGetChartSupport(): ChartSupport | null;

package/dist/types/modules/excel/chartsheet.d.ts

@@ -0,0 +1,102 @@
+import type { Chart } from "./chart/chart.js";
+import type { AddChartExOptions, ChartExModel } from "./chart/chart-ex-types.js";
+import type { AddChartOptions, AddComboChartOptions, ChartModel } from "./chart/types.js";
+import type { ChartsheetModel } from "./xlsx/xform/sheet/chartsheet-xform.js";
+export interface ChartsheetViewOptions {
+    /** Whether the chartsheet tab is selected in the workbook view. */
+    tabSelected?: boolean;
+    /** Zoom scale percentage. */
+    zoomScale?: number;
+    /**
+     * 0-based index into the workbook's `<bookViews>` list that this
+     * chartsheet view is bound to. Defaults to 0 (the primary view).
+     */
+    workbookViewId?: number;
+    /**
+     * When true the chartsheet scales to fill the window. Matches the
+     * OOXML `<sheetView zoomToFit="1"/>` attribute.
+     */
+    zoomToFit?: boolean;
+}
+export interface ChartsheetOptions extends ChartsheetViewOptions {
+    /** Sheet visibility state. */
+    state?: "visible" | "hidden" | "veryHidden";
+    /** Page margins for the chartsheet. */
+    pageMargins?: ChartsheetModel["pageMargins"];
+    /** Page setup for the chartsheet (CT_CsPageSetup). */
+    pageSetup?: ChartsheetModel["pageSetup"];
+}
+export interface AddChartsheetOptions extends ChartsheetOptions {
+    /** Chart to place on the chartsheet. */
+    chart: AddChartOptions | AddComboChartOptions | AddChartExOptions;
+}
+export interface AddPivotChartsheetOptions extends ChartsheetOptions {
+    /** Classic chart or combo chart to place on the chartsheet as a pivot chart. */
+    chart: AddChartOptions | AddComboChartOptions;
+}
+declare class Chartsheet {
+    private readonly _model;
+    private readonly _workbook?;
+    constructor(model: ChartsheetModel, workbook?: ChartsheetWorkbook);
+    get id(): number;
+    get sheetNo(): number;
+    get name(): string;
+    set name(value: string);
+    get state(): ChartsheetModel["state"];
+    set state(value: ChartsheetModel["state"]);
+    get chartNumber(): number | undefined;
+    get chartExNumber(): number | undefined;
+    get chartModel(): ChartModel | undefined;
+    get chartExModel(): ChartExModel | undefined;
+    /**
+     * Return the `Chart` wrapper for this chartsheet's single chart.
+     *
+     * The wrapper's `.worksheet` field is a {@link ChartsheetChartHost}
+     * rather than a real `Worksheet` — grid operations on it will throw a
+     * descriptive error. For anything grid-related, use the underlying
+     * {@link chartModel}/{@link chartExModel} directly or go through the
+     * `Chartsheet` methods ({@link replaceChart}, {@link rename}, …).
+     */
+    get chart(): Chart | undefined;
+    get isChartEx(): boolean;
+    get model(): ChartsheetModel;
+    get pageMargins(): ChartsheetModel["pageMargins"];
+    set pageMargins(value: ChartsheetModel["pageMargins"]);
+    get pageSetup(): ChartsheetModel["pageSetup"];
+    set pageSetup(value: ChartsheetModel["pageSetup"]);
+    get tabSelected(): boolean | undefined;
+    set tabSelected(value: boolean | undefined);
+    get zoomScale(): number | undefined;
+    set zoomScale(value: number | undefined);
+    get workbookViewId(): number | undefined;
+    set workbookViewId(value: number | undefined);
+    get zoomToFit(): boolean | undefined;
+    set zoomToFit(value: boolean | undefined);
+    rename(name: string): boolean;
+    remove(): boolean;
+    copy(name?: string): Chartsheet | undefined;
+    replaceChart(chart: AddChartsheetOptions["chart"]): boolean;
+}
+interface ChartsheetWorkbook {
+    getChartEntry(chartNumber: number): {
+        model: ChartModel;
+    } | undefined;
+    getChartExStructuredEntry(chartExNumber: number): {
+        model: ChartExModel;
+    } | undefined;
+    renameChartsheet(nameOrIndex: string | number, name: string): boolean;
+    removeChartsheet(nameOrIndex: string | number): boolean;
+    copyChartsheet(nameOrIndex: string | number, name?: string): Chartsheet | undefined;
+    replaceChartsheetChart(nameOrIndex: string | number, chart: AddChartsheetOptions["chart"]): boolean;
+    /**
+     * Validate a sheet name against Excel's unified namespace (both
+     * worksheets and chartsheets). See `Workbook.validateSheetName` for
+     * the full contract. Declared here so `Chartsheet.name` setter can
+     * route through it without widening the narrow host interface to
+     * the full `Workbook` type.
+     */
+    validateSheetName(name: string, existing?: {
+        name: string;
+    }): string;
+}
+export { Chartsheet };

package/dist/types/modules/excel/defined-names.d.ts

@@ -26,6 +26,14 @@ interface DefinedNameModel {
      * - "opaque": unrecognised content preserved for round-trip — stored in opaqueMap
      */
     kind?: "reference" | "formula" | "opaque";
+    /**
+     * `definedName/@hidden` — when `true`, emits `hidden="1"` on the
+     * XML element. Used by chartEx `_xlchart.vN.M` defined names that
+     * Excel creates automatically for every chartEx data reference;
+     * these names are infrastructure, never intended for users, so
+     * Excel hides them from the Name Manager UI.
+     */
+    hidden?: boolean;
 }
 /** Stored entry for an opaque (unrecognised) defined name. */
 interface OpaqueEntry {
@@ -43,6 +51,13 @@ declare class DefinedNames {
      * If a key is not in this map, the name is workbook-scoped (global).
      */
     localSheetIdMap: Record<string, number>;
+    /**
+     * Tracks the `hidden` flag for each storage key. Used by chartEx
+     * `_xlchart.vN.M` infrastructure names — Excel emits them with
+     * `hidden="1"` to suppress the Name Manager UI. A missing key
+     * means "not hidden" (the default).
+     */
+    hiddenMap: Record<string, boolean>;
     /**
      * Opaque defined names: storageKey → original text + optional localSheetId.
      */
@@ -70,6 +85,26 @@ declare class DefinedNames {
     constructor(probe?: SyntaxProbe);
     getMatrix(name: string): CellMatrix;
     add(locStr: string, name: string): void;
+    /**
+     * 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: string, name: string): void;
     addEx(location: CellLocation, name: string): void;
     /**
      * Register a formula-based defined name.

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