@rowsncolumns/toolkit 24.4.1

package/dist/esm/exporter/xlsx/sparkline-builder.js

@@ -0,0 +1,437 @@
+import { cellToAddress } from "@rowsncolumns/utils";
+/**
+ * Parse a SPARKLINE formula to extract data range and options
+ * Formula format: =SPARKLINE(A1:E1,{"charttype","column","color","#FF0000"})
+ */
+export function parseSparklineFormula(formula, sheetName) {
+    // Match SPARKLINE formula
+    const sparklineMatch = formula.match(/^=SPARKLINE\s*\(\s*([^,)]+)(?:\s*,\s*\{([^}]*)\})?\s*\)$/i);
+    if (!sparklineMatch)
+        return null;
+    let dataRange = sparklineMatch[1].trim();
+    const optionsStr = sparklineMatch[2];
+    // If the range doesn't have a sheet prefix, add current sheet name
+    if (!dataRange.includes("!")) {
+        dataRange = `${sheetName}!${dataRange}`;
+    }
+    // Parse options
+    let chartType = "line";
+    let color;
+    const opts = {};
+    const parseBool = (v) => {
+        const upper = v.toUpperCase();
+        if (upper === "TRUE" || upper === "1")
+            return true;
+        if (upper === "FALSE" || upper === "0")
+            return false;
+        return undefined;
+    };
+    const parseNum = (v) => {
+        const n = parseFloat(v);
+        return Number.isFinite(n) ? n : undefined;
+    };
+    if (optionsStr) {
+        // Tokenize on commas, strip outer quotes. The grammar is loose —
+        // Sheets accepts both `{"key","value", "key2","value2"}` and
+        // semicolon-separated pair forms — but our parser side always
+        // emits the comma form, so that's what we accept on the way back.
+        const tokens = optionsStr
+            .split(/[,;]/)
+            .map((t) => t.trim().replace(/^"|"$/g, ""));
+        for (let i = 0; i < tokens.length - 1; i += 2) {
+            const key = tokens[i].toLowerCase();
+            const value = tokens[i + 1];
+            switch (key) {
+                case "charttype":
+                    if (value === "column")
+                        chartType = "column";
+                    else if (value === "winloss")
+                        chartType = "stacked";
+                    break;
+                case "color":
+                    color = value;
+                    break;
+                case "emptycells":
+                    if (value === "gap" || value === "zero" || value === "span") {
+                        opts.emptyCellsAs = value;
+                    }
+                    break;
+                case "dateaxis": {
+                    const b = parseBool(value);
+                    if (b)
+                        opts.dateAxis = true;
+                    break;
+                }
+                case "markers": {
+                    const b = parseBool(value);
+                    if (b)
+                        opts.markers = true;
+                    break;
+                }
+                // Two key spellings are accepted for the highlight flags:
+                // the new `high`/`low`/…  names that match
+                // `SparkLineResultOptions` and the legacy `highpoint`/
+                // `lowpoint`/… names that the parser used to emit. Keep both
+                // so user-typed formulas and round-tripped files both work.
+                case "high":
+                case "highpoint": {
+                    const b = parseBool(value);
+                    if (b)
+                        opts.high = true;
+                    break;
+                }
+                case "low":
+                case "lowpoint": {
+                    const b = parseBool(value);
+                    if (b)
+                        opts.low = true;
+                    break;
+                }
+                case "first":
+                case "firstpoint": {
+                    const b = parseBool(value);
+                    if (b)
+                        opts.first = true;
+                    break;
+                }
+                case "last":
+                case "lastpoint": {
+                    const b = parseBool(value);
+                    if (b)
+                        opts.last = true;
+                    break;
+                }
+                case "negative":
+                case "negativepoints": {
+                    const b = parseBool(value);
+                    if (b)
+                        opts.negative = true;
+                    break;
+                }
+                case "colorhigh":
+                    opts.colorHigh = value;
+                    break;
+                case "colorlow":
+                    opts.colorLow = value;
+                    break;
+                case "colorfirst":
+                    opts.colorFirst = value;
+                    break;
+                case "colorlast":
+                    opts.colorLast = value;
+                    break;
+                case "colormarkers":
+                    opts.colorMarkers = value;
+                    break;
+                case "colornegative":
+                    opts.colorNegative = value;
+                    break;
+                case "axis": {
+                    const b = parseBool(value);
+                    if (b)
+                        opts.displayXAxis = true;
+                    break;
+                }
+                case "rtl": {
+                    // Sheets' SPARKLINE option name for OOXML `rightToLeft`.
+                    const b = parseBool(value);
+                    if (b)
+                        opts.rightToLeft = true;
+                    break;
+                }
+                case "displayhidden": {
+                    const b = parseBool(value);
+                    if (b)
+                        opts.displayHidden = true;
+                    break;
+                }
+                case "lineweight": {
+                    const n = parseNum(value);
+                    if (n != null)
+                        opts.lineWeight = n;
+                    break;
+                }
+                case "max": {
+                    const n = parseNum(value);
+                    if (n != null)
+                        opts.manualMax = n;
+                    break;
+                }
+                case "min": {
+                    const n = parseNum(value);
+                    if (n != null)
+                        opts.manualMin = n;
+                    break;
+                }
+                case "minaxistype":
+                    if (value === "individual" ||
+                        value === "group" ||
+                        value === "custom") {
+                        opts.minAxisType = value;
+                    }
+                    break;
+                case "maxaxistype":
+                    if (value === "individual" ||
+                        value === "group" ||
+                        value === "custom") {
+                        opts.maxAxisType = value;
+                    }
+                    break;
+            }
+        }
+    }
+    return { dataRange, chartType, color, ...opts };
+}
+/**
+ * Detect SPARKLINE formulas in a sheet and extract sparkline info
+ */
+export function detectSparklines(sheet, rowData) {
+    const sparklines = [];
+    for (const [rowIndexStr, row] of Object.entries(rowData)) {
+        const rowIndex = parseInt(rowIndexStr, 10);
+        for (const [colIndexStr, cell] of Object.entries(row)) {
+            const columnIndex = parseInt(colIndexStr, 10);
+            const formula = cell?.ue?.fv || cell?.userEnteredValue?.formulaValue;
+            if (formula && formula.toUpperCase().startsWith("=SPARKLINE(")) {
+                const parsed = parseSparklineFormula(formula, sheet.title);
+                if (parsed) {
+                    const targetCell = cellToAddress({
+                        rowIndex,
+                        columnIndex,
+                    });
+                    if (targetCell) {
+                        const { dataRange, chartType, color, ...axis } = parsed;
+                        sparklines.push({
+                            targetCell,
+                            dataRange,
+                            type: chartType,
+                            color,
+                            rowIndex,
+                            columnIndex,
+                            ...axis,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return sparklines;
+}
+/**
+ * Group sparklines by their full style fingerprint — type + color +
+ * every axis option that affects rendering. Two sparklines only share
+ * a `<x14:sparklineGroup>` when every attribute matches, otherwise
+ * OOXML's "one set of attrs per group" model would silently merge
+ * different settings into one.
+ */
+function groupSparklines(sparklines) {
+    const groups = new Map();
+    const fingerprintAxis = (s) => [
+        s.emptyCellsAs ?? "",
+        s.dateAxis ? "1" : "",
+        s.markers ? "1" : "",
+        s.high ? "1" : "",
+        s.low ? "1" : "",
+        s.first ? "1" : "",
+        s.last ? "1" : "",
+        s.negative ? "1" : "",
+        s.displayXAxis ? "1" : "",
+        s.displayHidden ? "1" : "",
+        s.rightToLeft ? "1" : "",
+        s.lineWeight ?? "",
+        s.manualMax ?? "",
+        s.manualMin ?? "",
+        s.minAxisType ?? "",
+        s.maxAxisType ?? "",
+        s.colorHigh ?? "",
+        s.colorLow ?? "",
+        s.colorFirst ?? "",
+        s.colorLast ?? "",
+        s.colorMarkers ?? "",
+        s.colorNegative ?? "",
+    ].join("|");
+    for (const sparkline of sparklines) {
+        const key = `${sparkline.type}|${sparkline.color || ""}|${fingerprintAxis(sparkline)}`;
+        if (!groups.has(key)) {
+            groups.set(key, {
+                type: sparkline.type,
+                color: sparkline.color,
+                sparklines: [],
+                emptyCellsAs: sparkline.emptyCellsAs,
+                dateAxis: sparkline.dateAxis,
+                markers: sparkline.markers,
+                high: sparkline.high,
+                low: sparkline.low,
+                first: sparkline.first,
+                last: sparkline.last,
+                negative: sparkline.negative,
+                displayXAxis: sparkline.displayXAxis,
+                displayHidden: sparkline.displayHidden,
+                rightToLeft: sparkline.rightToLeft,
+                lineWeight: sparkline.lineWeight,
+                manualMax: sparkline.manualMax,
+                manualMin: sparkline.manualMin,
+                minAxisType: sparkline.minAxisType,
+                maxAxisType: sparkline.maxAxisType,
+                colorHigh: sparkline.colorHigh,
+                colorLow: sparkline.colorLow,
+                colorFirst: sparkline.colorFirst,
+                colorLast: sparkline.colorLast,
+                colorMarkers: sparkline.colorMarkers,
+                colorNegative: sparkline.colorNegative,
+            });
+        }
+        groups.get(key).sparklines.push(sparkline);
+    }
+    return Array.from(groups.values());
+}
+/**
+ * Convert hex color #RRGGBB to Excel's ARGB format FFRRGGBB
+ */
+function toExcelColor(color) {
+    // Remove # if present
+    const hex = color.replace(/^#/, "");
+    // Add alpha channel (FF = fully opaque)
+    return `FF${hex.toUpperCase()}`;
+}
+// Default colors for sparklines (Excel theme colors)
+const DEFAULT_SPARKLINE_COLOR = "#4472C4"; // Excel default blue
+const DEFAULT_MARKER_COLOR = "#4472C4"; // Same as line color
+const DEFAULT_HIGH_COLOR = "#56A26B"; // Green for high point
+const DEFAULT_LOW_COLOR = "#C55A5A"; // Red for low point
+const DEFAULT_NEGATIVE_COLOR = "#C55A5A"; // Red for negative values
+/**
+ * Build sparkline groups XML for worksheet extLst
+ * Returns null if no sparklines detected
+ */
+export function buildSparklineGroupsXml(sheet, rowData) {
+    const sparklines = detectSparklines(sheet, rowData);
+    if (sparklines.length === 0) {
+        return null;
+    }
+    const groups = groupSparklines(sparklines);
+    let groupsXml = "";
+    for (const group of groups) {
+        // Use specified color or default
+        const seriesColor = group.color || DEFAULT_SPARKLINE_COLOR;
+        // Build sparkline group attributes. Each axis option round-trips
+        // 1:1 with its OOXML attribute name. When a value was explicitly
+        // parsed off the formula we emit it verbatim; otherwise we keep
+        // the legacy "sensible defaults" path so plain `SPARKLINE(range)`
+        // formulas still get readable highlights when exported.
+        let groupAttrs = "";
+        if (group.type !== "line") {
+            groupAttrs += ` type="${group.type}"`;
+        }
+        if (group.lineWeight != null) {
+            groupAttrs += ` lineWeight="${group.lineWeight}"`;
+        }
+        if (group.dateAxis)
+            groupAttrs += ` dateAxis="1"`;
+        if (group.emptyCellsAs) {
+            groupAttrs += ` displayEmptyCellsAs="${group.emptyCellsAs}"`;
+        }
+        if (group.markers)
+            groupAttrs += ` markers="1"`;
+        if (group.high)
+            groupAttrs += ` high="1"`;
+        if (group.low)
+            groupAttrs += ` low="1"`;
+        if (group.first)
+            groupAttrs += ` first="1"`;
+        if (group.last)
+            groupAttrs += ` last="1"`;
+        if (group.negative)
+            groupAttrs += ` negative="1"`;
+        if (group.displayXAxis)
+            groupAttrs += ` displayXAxis="1"`;
+        if (group.displayHidden)
+            groupAttrs += ` displayHidden="1"`;
+        if (group.rightToLeft)
+            groupAttrs += ` rightToLeft="1"`;
+        if (group.manualMax != null)
+            groupAttrs += ` manualMax="${group.manualMax}"`;
+        if (group.manualMin != null)
+            groupAttrs += ` manualMin="${group.manualMin}"`;
+        if (group.minAxisType)
+            groupAttrs += ` minAxisType="${group.minAxisType}"`;
+        if (group.maxAxisType)
+            groupAttrs += ` maxAxisType="${group.maxAxisType}"`;
+        // Legacy "sensible defaults" — only when the formula didn't
+        // explicitly set markers / high / low / negative. Preserves the
+        // existing behavior for plain `SPARKLINE(range)` formulas that
+        // came through without options.
+        const hasExplicitHighlights = group.markers ||
+            group.high ||
+            group.low ||
+            group.first ||
+            group.last ||
+            group.negative;
+        if (!hasExplicitHighlights) {
+            if (group.type === "line") {
+                groupAttrs += ` markers="1" high="1" low="1"`;
+            }
+            else if (group.type === "column" || group.type === "stacked") {
+                groupAttrs += ` high="1" low="1" negative="1"`;
+            }
+        }
+        // Build color elements. Per-point colors come from the original
+        // workbook when present (round-trip path); otherwise we fall back
+        // to readable defaults so plain `SPARKLINE(range)` formulas still
+        // get sensible highlights.
+        let colorsXml = "";
+        colorsXml += `<x14:colorSeries rgb="${toExcelColor(seriesColor)}"/>`;
+        if (group.type === "column" || group.type === "stacked") {
+            colorsXml += `<x14:colorNegative rgb="${toExcelColor(group.colorNegative ?? DEFAULT_NEGATIVE_COLOR)}"/>`;
+        }
+        else if (group.colorNegative) {
+            colorsXml += `<x14:colorNegative rgb="${toExcelColor(group.colorNegative)}"/>`;
+        }
+        if (group.type === "line") {
+            colorsXml += `<x14:colorMarkers rgb="${toExcelColor(group.colorMarkers ?? seriesColor)}"/>`;
+        }
+        else if (group.colorMarkers) {
+            colorsXml += `<x14:colorMarkers rgb="${toExcelColor(group.colorMarkers)}"/>`;
+        }
+        if (group.colorFirst) {
+            colorsXml += `<x14:colorFirst rgb="${toExcelColor(group.colorFirst)}"/>`;
+        }
+        if (group.colorLast) {
+            colorsXml += `<x14:colorLast rgb="${toExcelColor(group.colorLast)}"/>`;
+        }
+        colorsXml += `<x14:colorHigh rgb="${toExcelColor(group.colorHigh ?? DEFAULT_HIGH_COLOR)}"/>`;
+        colorsXml += `<x14:colorLow rgb="${toExcelColor(group.colorLow ?? DEFAULT_LOW_COLOR)}"/>`;
+        // Build individual sparklines
+        let sparklinesXml = "";
+        for (const sparkline of group.sparklines) {
+            sparklinesXml += `<x14:sparkline><xm:f>${sparkline.dataRange}</xm:f><xm:sqref>${sparkline.targetCell}</xm:sqref></x14:sparkline>`;
+        }
+        groupsXml += `<x14:sparklineGroup${groupAttrs}>${colorsXml}<x14:sparklines>${sparklinesXml}</x14:sparklines></x14:sparklineGroup>`;
+    }
+    return `<ext uri="{05C60535-1F16-4fd2-B633-F4F36F0B64E0}" xmlns:x14="http://schemas.microsoft.com/office/spreadsheetml/2009/9/main" xmlns:xm="http://schemas.microsoft.com/office/excel/2006/main"><x14:sparklineGroups xmlns:xm="http://schemas.microsoft.com/office/excel/2006/main">${groupsXml}</x14:sparklineGroups></ext>`;
+}
+/**
+ * Build combined extLst for worksheet (sparklines + slicers)
+ */
+export function buildWorksheetExtLst(sparklineExtXml, slicerExtXml) {
+    const parts = [];
+    if (sparklineExtXml) {
+        parts.push(sparklineExtXml);
+    }
+    if (slicerExtXml) {
+        parts.push(slicerExtXml);
+    }
+    if (parts.length === 0) {
+        return "";
+    }
+    return `<extLst>${parts.join("")}</extLst>`;
+}
+/**
+ * Check if a cell has a SPARKLINE formula and should NOT be exported as a formula
+ * (the formula will be converted to native Excel sparkline instead)
+ */
+export function isSparklineCell(cell) {
+    const formula = cell?.ue?.fv || cell?.userEnteredValue?.formulaValue;
+    return (typeof formula === "string" &&
+        formula.toUpperCase().startsWith("=SPARKLINE("));
+}

package/dist/esm/exporter/xlsx/style-builder.d.ts

@@ -0,0 +1,93 @@
+import type { CellData, CellFormat, Color, TextFormat } from "@rowsncolumns/spreadsheet";
+import { type CellXfs } from "@rowsncolumns/spreadsheet-state";
+type NamedCellStyleRecord = {
+    name: string;
+    xfId: number;
+    builtinId?: number;
+    iLevel?: number;
+    hidden?: boolean;
+    customBuiltin?: boolean;
+};
+type CustomTableStyleRecord = {
+    name: string;
+    pivot?: boolean;
+    elements: Array<{
+        type: string;
+        size?: number;
+        backgroundColor?: Color;
+        textColor?: Color;
+        bold?: boolean;
+        italic?: boolean;
+    }>;
+};
+export declare class StyleBuilder {
+    private numberFormats;
+    private fonts;
+    private fills;
+    private borders;
+    private namedCellStyles;
+    private customTableStyles;
+    /**
+     * Replace the named-cell-styles list emitted in `<cellStyles>`.
+     * Used for round-tripping the OOXML Heading 1 / Accent / Total /
+     * Good-Bad-Neutral gallery — the importer parses these from
+     * `xl/styles.xml` and exposes them on `workbook.workbookStyles.
+     * namedCellStyles`; hosts can forward that list back here.
+     *
+     * Excel requires at least a "Normal" entry pointing at xfId=0,
+     * builtinId=0 — when the supplied list doesn't contain one, we
+     * keep the default at the head of the list rather than risk
+     * emitting a file Excel rejects.
+     */
+    setNamedCellStyles(entries: NamedCellStyleRecord[]): void;
+    /**
+     * Replace the user-authored table-style list emitted in the
+     * `<tableStyles>` block. The exporter registers each element's
+     * format as a dxf at `toXml()` time, so callers pass self-contained
+     * records (no dxfIds to manage). Used for round-tripping the
+     * OOXML custom-table-style list from
+     * `workbook.workbookStyles.getCustomTableStyleExports()`.
+     */
+    setCustomTableStyles(entries: CustomTableStyleRecord[]): void;
+    private cellXfs;
+    private fontMap;
+    private fillMap;
+    private borderMap;
+    private formatMap;
+    private xfMap;
+    private dxfs;
+    private dxfMap;
+    constructor();
+    /**
+     * Replace the workbook default font (font id 0 — what every cell without
+     * an explicit font inherits). Callers pass the source workbook's parsed
+     * default (`WorkBook.getDefaultFont()`) so an imported workbook keeps its
+     * default typeface/size instead of the hardcoded Calibri 11. Must be
+     * called before any cell registration: cells explicitly styled with the
+     * old default must not collapse into font id 0.
+     */
+    setDefaultFont(format?: TextFormat | null): void;
+    registerCell<T extends CellData>(cell: T | null | undefined, cellXfs: CellXfs | null | undefined, 
+    /**
+     * Number format to use when the cell itself has none. Used by the
+     * exporter to layer in the precedent-derived number format on formula
+     * cells so Excel displays them correctly without requiring a recalc.
+     */
+    derivedNumberFormat?: CellFormat["numberFormat"]): number;
+    registerDifferentialFormat(format?: CellFormat | null): number | undefined;
+    private getNumberFormatId;
+    private getFontId;
+    private getFillId;
+    private getBorderId;
+    private serializeFont;
+    private buildFontRecord;
+    private buildFontXml;
+    private buildFillXml;
+    private buildGradientFillXml;
+    private serializeFill;
+    private serializeBorder;
+    private serializeDxf;
+    toXml(): string;
+}
+export {};
+//# sourceMappingURL=style-builder.d.ts.map

package/dist/esm/exporter/xlsx/style-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style-builder.d.ts","sourceRoot":"","sources":["../../../../exporter/xlsx/style-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,QAAQ,EACR,UAAU,EACV,KAAK,EAEL,UAAU,EACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAwF/D,KAAK,oBAAoB,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAKF,KAAK,sBAAsB,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,KAAK,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,eAAe,CAAC,EAAE,KAAK,CAAC;QACxB,SAAS,CAAC,EAAE,KAAK,CAAC;QAClB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC,CAAC;CACJ,CAAC;AAEF,qBAAa,YAAY;IACvB,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,KAAK,CAKX;IACF,OAAO,CAAC,KAAK,CAA+D;IAC5E,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,eAAe,CAErB;IACF,OAAO,CAAC,iBAAiB,CAAgC;IAEzD;;;;;;;;;;;OAWG;IACH,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,EAAE;IAUlD;;;;;;;OAOG;IACH,oBAAoB,CAAC,OAAO,EAAE,sBAAsB,EAAE;IAOtD,OAAO,CAAC,OAAO,CAOb;IAEF,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,IAAI,CAAmB;IAC/B,OAAO,CAAC,MAAM,CAA6B;;IAU3C;;;;;;;OAOG;IACH,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI;IASzC,YAAY,CAAC,CAAC,SAAS,QAAQ,EAC7B,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC1B,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS;IACnC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,UAAU,CAAC,cAAc,CAAC,GAC/C,MAAM;IAsET,0BAA0B,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI;IA0BrD,OAAO,CAAC,iBAAiB;IAoCzB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,SAAS;IA2DjB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,eAAe;IA8BvB,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,YAAY;IAqCpB,OAAO,CAAC,oBAAoB;IAyB5B,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,YAAY;IAMpB,KAAK;CAuJN"}