@rowsncolumns/toolkit 24.4.2 → 24.4.4

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

@@ -1456,34 +1456,6 @@ export const buildChartXml = (chart, sheetNameById) => {
         targetChart["c:ser"] = seriesContainer;
         chartSpace["c:chartSpace"]["c:chart"] = chartDoc;
     }
-    else if (chartType === "treemap" || chartType === "sunburst") {
-        const treeSpec = chart.spec;
-        const labelRef = formatRangeRef(getPrimarySource(treeSpec.labels?.[0]), sheetNameById);
-        const sizeRef = formatRangeRef(getPrimarySource(treeSpec.sizeData?.[0]), sheetNameById);
-        if (!labelRef || !sizeRef)
-            return undefined;
-        if (chartType === "sunburst") {
-            const pieChart = buildPieChart(labelRef, sizeRef, chartTitle, chartSubtitle);
-            chartSpace["c:chartSpace"]["c:chart"] = pieChart;
-        }
-        else {
-            const columnChart = cloneTemplate(column_json);
-            applyChartTitle(columnChart, chartTitle, chartTitleFmt, chartSubtitle);
-            const bar = columnChart["c:plotArea"]["c:barChart"];
-            const seriesContainer = bar["c:ser"];
-            const seriesNode = cloneTemplate(column_series);
-            seriesNode["c:idx"] = { a$: { val: "0" } };
-            seriesNode["c:order"] = { a$: { val: "0" } };
-            seriesNode["c:cat"] = {
-                "c:strRef": {
-                    "c:f": labelRef,
-                },
-            };
-            seriesNode["c:val"]["c:numRef"]["c:f"] = sizeRef;
-            seriesContainer.push(seriesNode);
-            chartSpace["c:chartSpace"]["c:chart"] = columnChart;
-        }
-    }
     else {
         return undefined;
     }
@@ -1492,6 +1464,12 @@ export const buildChartXml = (chart, sheetNameById) => {
     // chartType-agnostic and intentionally run last so per-type branches
     // don't have to know about them.
     applyChartFormatting(chartSpace, chart.spec, sheetNameById);
+    // 3-D / surface variants (sourceChartType BAR_3D, LINE_3D, PIE_3D,
+    // AREA_3D, SURFACE, SURFACE_3D) — swap the 2-D chart group for its
+    // OOXML 3-D element and add `<c:view3D>`. Runs after the formatting
+    // pass so data labels / overlays land in the container first and are
+    // carried across by the rename.
+    applyThreeDChartType(chartSpace["c:chartSpace"]["c:chart"], chart.spec.sourceChartType);
     // `<c:roundedCorners val="1"/>` lives at the chartSpace root (sibling
     // of `<c:chart>`). Default per OOXML §21.2.2.183 is `false`; only
     // emit when the spec opted in so files imported without the element
@@ -1502,6 +1480,161 @@ export const buildChartXml = (chart, sheetNameById) => {
     const xml = chartBuilder.build(chartSpace);
     return `${XML_DECLARATION}${xml}`;
 };
+// -------------------------- 3-D / surface --------------------------
+/** Series-axis id for the 3-D chart groups that take a third axis. */
+const SER_AX_ID = "1789284465";
+/**
+ * How each 3-D class maps onto its 2-D chart group: which container it
+ * replaces, the element it becomes, and how many `<c:axId>` refs the
+ * schema wants (0 = no axes, 3 = adds a series axis).
+ */
+const THREE_D_CHART_GROUPS = {
+    BAR_3D: { from: "c:barChart", to: "c:bar3DChart", axes: 2 },
+    LINE_3D: { from: "c:lineChart", to: "c:line3DChart", axes: 3 },
+    PIE_3D: { from: "c:pieChart", to: "c:pie3DChart", axes: 0 },
+    AREA_3D: { from: "c:areaChart", to: "c:area3DChart", axes: 2 },
+    SURFACE: { from: "c:areaChart", to: "c:surfaceChart", axes: 2 },
+    SURFACE_3D: { from: "c:areaChart", to: "c:surface3DChart", axes: 3 },
+};
+const normalizeThreeDToken = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const token = value.trim().toUpperCase();
+    return token in THREE_D_CHART_GROUPS ? token : undefined;
+};
+/** Copy `keys` (in order) from `source` into `target`, skipping absent ones. */
+const pickKeys = (target, source, keys) => {
+    for (const key of keys) {
+        if (source[key] !== undefined)
+            target[key] = source[key];
+    }
+};
+/**
+ * Rebuild the 2-D chart group as its 3-D element with the CT_*3DChart
+ * child sequence. Element order matters to Excel, so each shape is
+ * written out explicitly rather than renaming the key in place:
+ *   bar3DChart:     barDir, grouping, varyColors, ser, dLbls, gapWidth, shape, axId
+ *   line3DChart:    grouping, varyColors, ser, dLbls, axId×3
+ *   pie3DChart:     varyColors, ser, dLbls
+ *   area3DChart:    grouping, varyColors, ser, dLbls, axId
+ *   surfaceChart:   wireframe, ser, axId          (surface3DChart: axId×3)
+ */
+const buildThreeDChartGroup = (token, group, axIds) => {
+    const node = {};
+    switch (token) {
+        case "BAR_3D":
+            pickKeys(node, group, ["c:barDir", "c:grouping", "c:varyColors"]);
+            pickKeys(node, group, ["c:ser", "c:dLbls", "c:gapWidth"]);
+            node["c:shape"] = { a$: { val: "box" } };
+            node["c:axId"] = axIds;
+            return node;
+        case "LINE_3D":
+        case "AREA_3D":
+            pickKeys(node, group, ["c:grouping", "c:varyColors", "c:ser", "c:dLbls"]);
+            node["c:axId"] = axIds;
+            return node;
+        case "PIE_3D":
+            pickKeys(node, group, ["c:varyColors", "c:ser", "c:dLbls"]);
+            return node;
+        case "SURFACE":
+        case "SURFACE_3D":
+            node["c:wireframe"] = { a$: { val: "0" } };
+            pickKeys(node, group, ["c:ser"]);
+            node["c:axId"] = axIds;
+            return node;
+    }
+};
+/** `<c:serAx>` for the 3-D groups whose schema takes a third (depth) axis. */
+const buildSerAxNode = (valAxId) => ({
+    "c:axId": { a$: { val: SER_AX_ID } },
+    "c:scaling": { "c:orientation": { a$: { val: "minMax" } } },
+    "c:delete": { a$: { val: "0" } },
+    "c:axPos": { a$: { val: "b" } },
+    "c:majorTickMark": { a$: { val: "out" } },
+    "c:minorTickMark": { a$: { val: "none" } },
+    "c:tickLblPos": { a$: { val: "nextTo" } },
+    "c:crossAx": { a$: { val: valAxId } },
+    "c:crosses": { a$: { val: "autoZero" } },
+});
+/** `<c:view3D>` — Excel's default camera for each class (CT_View3D order). */
+const buildView3DNode = (token) => {
+    if (token === "PIE_3D") {
+        return {
+            "c:rotX": { a$: { val: "30" } },
+            "c:rotY": { a$: { val: "0" } },
+            "c:rAngAx": { a$: { val: "0" } },
+        };
+    }
+    if (token === "SURFACE" || token === "SURFACE_3D") {
+        // Right-angle axes are not allowed on surfaces; use a perspective view.
+        return {
+            "c:rotX": { a$: { val: "15" } },
+            "c:rotY": { a$: { val: "20" } },
+            "c:rAngAx": { a$: { val: "0" } },
+            "c:perspective": { a$: { val: "30" } },
+        };
+    }
+    return {
+        "c:rotX": { a$: { val: "15" } },
+        "c:rotY": { a$: { val: "20" } },
+        "c:rAngAx": { a$: { val: "1" } },
+    };
+};
+/**
+ * Turn an assembled 2-D `<c:chart>` into its 3-D variant when the spec
+ * carries a 3-D `sourceChartType`: the chart group is swapped for the
+ * matching `c:*3DChart` / `c:surfaceChart` element, a `<c:serAx>` is
+ * added where the schema takes three axes, and `<c:view3D>` is inserted
+ * before `<c:plotArea>`. No-op for 2-D specs or when the token doesn't
+ * match the emitted chart group (the 2-D chart is left untouched).
+ */
+const applyThreeDChartType = (chartNode, sourceChartType) => {
+    const token = normalizeThreeDToken(sourceChartType);
+    if (!token || !chartNode)
+        return;
+    const plotArea = chartNode["c:plotArea"];
+    if (!plotArea)
+        return;
+    const { from, to, axes } = THREE_D_CHART_GROUPS[token];
+    const group = plotArea[from];
+    if (!group || Array.isArray(group))
+        return;
+    const existingAxIds = Array.isArray(group["c:axId"])
+        ? group["c:axId"]
+        : group["c:axId"]
+            ? [group["c:axId"]]
+            : [];
+    const valAxId = existingAxIds[1]?.a$?.val ?? existingAxIds[0]?.a$?.val ?? "0";
+    const axIds = axes === 3
+        ? [...existingAxIds.slice(0, 2), { a$: { val: SER_AX_ID } }]
+        : existingAxIds.slice(0, 2);
+    // Rebuild plotArea preserving element order, swapping the chart group
+    // and appending the series axis after the value axis when needed.
+    const rebuiltPlotArea = {};
+    for (const [key, value] of Object.entries(plotArea)) {
+        if (key === from) {
+            rebuiltPlotArea[to] = buildThreeDChartGroup(token, group, axIds);
+            continue;
+        }
+        rebuiltPlotArea[key] = value;
+        if (key === "c:valAx" && axes === 3) {
+            rebuiltPlotArea["c:serAx"] = buildSerAxNode(valAxId);
+        }
+    }
+    // Rebuild the chart node so `<c:view3D>` lands before `<c:plotArea>`.
+    const rebuiltChart = {};
+    for (const [key, value] of Object.entries(chartNode)) {
+        if (key === "c:plotArea") {
+            rebuiltChart["c:view3D"] = buildView3DNode(token);
+            rebuiltChart[key] = rebuiltPlotArea;
+            continue;
+        }
+        rebuiltChart[key] = value;
+    }
+    for (const key of Object.keys(chartNode))
+        delete chartNode[key];
+    Object.assign(chartNode, rebuiltChart);
+};
 // -------------------------- Phase 5 helpers --------------------------
 const LEGEND_POS = {
     top: "t",

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

@@ -0,0 +1,36 @@
+import type { EmbeddedChart, SheetRange, TreemapChart } from "@rowsncolumns/spreadsheet";
+/**
+ * Excel 2016+ "chartex" writer (`xl/charts/chartEx{N}.xml`) — the inverse
+ * of `excel-parser/plugins/xlsx/chartex.ts`. Treemap and sunburst have no
+ * `c:chartSpace` representation; Excel stores them as a `cx:chartSpace`
+ * whose series `layoutId` names the chart and whose data is a hierarchy
+ * `strDim type="cat"` (parent columns first, leaf last) plus a
+ * `numDim type="size"`. Anchored through `mc:AlternateContent` requiring the
+ * `cx1` namespace.
+ */
+export declare const CHART_EX_REL_TYPE = "http://schemas.microsoft.com/office/2014/relationships/chartEx";
+export declare const CHART_EX_CONTENT_TYPE = "application/vnd.ms-office.chartex+xml";
+export declare const CHART_EX_NS = "http://schemas.microsoft.com/office/drawing/2014/chartex";
+/** Chart types that live in a chartex part rather than a `c:chartSpace`. */
+export declare const isChartExType: (chartType: string | undefined | null) => chartType is "treemap" | "sunburst";
+/**
+ * The hierarchy reference: parent columns + the leaf column merged into one
+ * contiguous range when they sit side by side on the same sheet over the same
+ * rows (how Excel lays a treemap out); otherwise the leaf labels alone.
+ */
+export declare const hierarchyRange: (spec: TreemapChart) => SheetRange | undefined;
+/** `xl/charts/chartEx{N}.xml` for a treemap / sunburst; undefined when the spec has no data. */
+export declare const buildChartExXml: (chart: EmbeddedChart, sheetNameById: Map<number, string>) => string | undefined;
+/**
+ * The drawing anchor body for a chartex part: Excel's `mc:AlternateContent`
+ * with a `cx1`-requiring choice holding the graphic frame. No `mc:Fallback`
+ * is written — Excel opens the file without one, and a fallback text box
+ * would import as a stray shape in consumers that do not know chartex.
+ */
+export declare const buildChartExGraphicFrameXml: ({ relId, frameId, widthEmu, heightEmu, }: {
+    relId: string;
+    frameId: number;
+    widthEmu: number;
+    heightEmu: number;
+}) => string;
+//# sourceMappingURL=chartex-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chartex-builder.d.ts","sourceRoot":"","sources":["../../../../exporter/xlsx/chartex-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,aAAa,EACb,UAAU,EACV,YAAY,EACb,MAAM,2BAA2B,CAAC;AAGnC;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,mEACoC,CAAC;AACnE,eAAO,MAAM,qBAAqB,0CAA0C,CAAC;AAC7E,eAAO,MAAM,WAAW,6DAA6D,CAAC;AAyBtF,4EAA4E;AAC5E,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,GAAG,SAAS,GAAG,IAAI,wCACb,CAAC;AAItD;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,YAAY,KAAG,UAAU,GAAG,SAsBhE,CAAC;AAEF,gGAAgG;AAChG,eAAO,MAAM,eAAe,GAC1B,OAAO,aAAa,EACpB,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KACjC,MAAM,GAAG,SAkCX,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GAAI,0CAKzC;IACD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,WACkhB,CAAC"}

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

@@ -0,0 +1,97 @@
+import { cellRangeToAddress } from "@rowsncolumns/utils";
+/**
+ * Excel 2016+ "chartex" writer (`xl/charts/chartEx{N}.xml`) — the inverse
+ * of `excel-parser/plugins/xlsx/chartex.ts`. Treemap and sunburst have no
+ * `c:chartSpace` representation; Excel stores them as a `cx:chartSpace`
+ * whose series `layoutId` names the chart and whose data is a hierarchy
+ * `strDim type="cat"` (parent columns first, leaf last) plus a
+ * `numDim type="size"`. Anchored through `mc:AlternateContent` requiring the
+ * `cx1` namespace.
+ */
+export const CHART_EX_REL_TYPE = "http://schemas.microsoft.com/office/2014/relationships/chartEx";
+export const CHART_EX_CONTENT_TYPE = "application/vnd.ms-office.chartex+xml";
+export const CHART_EX_NS = "http://schemas.microsoft.com/office/drawing/2014/chartex";
+const CHART_EX_1_NS = "http://schemas.microsoft.com/office/drawing/2015/9/8/chartex";
+const A_NS = "http://schemas.openxmlformats.org/drawingml/2006/main";
+const R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+const XML_DECLARATION = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n`;
+/** `{XXXXXXXX-XXXX-4XXX-XXXX-XXXXXXXXXXXX}` — the series `uniqueId` Excel expects. */
+const guid = () => {
+    const hex = () => Math.floor(Math.random() * 16).toString(16).toUpperCase();
+    const block = (n) => Array.from({ length: n }, hex).join("");
+    return `{${block(8)}-${block(4)}-4${block(3)}-${block(4)}-${block(12)}}`;
+};
+/** `'Sheet'!A2:B9` → `'Sheet'!$A$2:$B$9` — Excel writes chart data references absolute. */
+const absoluteRef = (ref) => {
+    const bang = ref.lastIndexOf("!");
+    const sheetPart = bang >= 0 ? ref.slice(0, bang + 1) : "";
+    const cells = bang >= 0 ? ref.slice(bang + 1) : ref;
+    return `${sheetPart}${cells.replace(/\$?([A-Z]+)\$?(\d+)/g, "$$$1$$$2")}`;
+};
+const escapeText = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/** Chart types that live in a chartex part rather than a `c:chartSpace`. */
+export const isChartExType = (chartType) => chartType === "treemap" || chartType === "sunburst";
+const primarySource = (entry) => entry?.sources?.[0];
+/**
+ * The hierarchy reference: parent columns + the leaf column merged into one
+ * contiguous range when they sit side by side on the same sheet over the same
+ * rows (how Excel lays a treemap out); otherwise the leaf labels alone.
+ */
+export const hierarchyRange = (spec) => {
+    const leaf = primarySource(spec.labels?.[0]);
+    if (!leaf)
+        return undefined;
+    const parents = (spec.parentLabels ?? [])
+        .map((entry) => primarySource(entry))
+        .filter((range) => Boolean(range));
+    if (!parents.length)
+        return leaf;
+    const sameRows = parents.every((p) => p.sheetId === leaf.sheetId &&
+        p.startRowIndex === leaf.startRowIndex &&
+        p.endRowIndex === leaf.endRowIndex);
+    if (!sameRows)
+        return leaf;
+    const columns = [...parents, leaf].map((r) => r.startColumnIndex).sort((a, b) => a - b);
+    const contiguous = columns.every((c, i) => i === 0 || c === columns[i - 1] + 1);
+    if (!contiguous || columns[columns.length - 1] !== leaf.startColumnIndex) {
+        return leaf;
+    }
+    return { ...leaf, startColumnIndex: columns[0], endColumnIndex: leaf.endColumnIndex };
+};
+/** `xl/charts/chartEx{N}.xml` for a treemap / sunburst; undefined when the spec has no data. */
+export const buildChartExXml = (chart, sheetNameById) => {
+    const spec = chart.spec;
+    if (!isChartExType(spec.chartType))
+        return undefined;
+    const cat = hierarchyRange(spec);
+    const size = primarySource(spec.sizeData?.[0]);
+    if (!cat || !size)
+        return undefined;
+    const catAddress = cellRangeToAddress(sheetNameById.get(cat.sheetId), cat);
+    const sizeAddress = cellRangeToAddress(sheetNameById.get(size.sheetId), size);
+    if (!catAddress || !sizeAddress)
+        return undefined;
+    const catRef = absoluteRef(catAddress);
+    const sizeRef = absoluteRef(sizeAddress);
+    const title = chart.spec.title;
+    const titleXml = title
+        ? `<cx:title pos="t" align="ctr" overlay="0"><cx:tx><cx:txData><cx:v>${escapeText(title)}</cx:v></cx:txData></cx:tx></cx:title>`
+        : "";
+    const isTreemap = spec.chartType === "treemap";
+    const dataLabels = isTreemap
+        ? `<cx:dataLabels pos="inEnd"><cx:visibility seriesName="0" categoryName="1" value="0"/></cx:dataLabels>`
+        : `<cx:dataLabels><cx:visibility seriesName="0" categoryName="1" value="0"/></cx:dataLabels>`;
+    const layoutPr = isTreemap
+        ? `<cx:layoutPr><cx:parentLabelLayout val="banner"/></cx:layoutPr>`
+        : "";
+    const legend = isTreemap ? `<cx:legend pos="t" align="ctr" overlay="0"/>` : "";
+    return `${XML_DECLARATION}<cx:chartSpace xmlns:a="${A_NS}" xmlns:r="${R_NS}" xmlns:cx="${CHART_EX_NS}"><cx:chartData><cx:data id="0"><cx:strDim type="cat"><cx:f>${escapeText(catRef)}</cx:f></cx:strDim><cx:numDim type="size"><cx:f>${escapeText(sizeRef)}</cx:f></cx:numDim></cx:data></cx:chartData><cx:chart>${titleXml}<cx:plotArea><cx:plotAreaRegion><cx:series layoutId="${spec.chartType}" uniqueId="${guid()}">${dataLabels}<cx:dataId val="0"/>${layoutPr}</cx:series></cx:plotAreaRegion></cx:plotArea>${legend}</cx:chart></cx:chartSpace>`;
+};
+/**
+ * The drawing anchor body for a chartex part: Excel's `mc:AlternateContent`
+ * with a `cx1`-requiring choice holding the graphic frame. No `mc:Fallback`
+ * is written — Excel opens the file without one, and a fallback text box
+ * would import as a stray shape in consumers that do not know chartex.
+ */
+export const buildChartExGraphicFrameXml = ({ relId, frameId, widthEmu, heightEmu, }) => `<mc:AlternateContent xmlns:mc="${MC_NS}"><mc:Choice xmlns:cx1="${CHART_EX_1_NS}" Requires="cx1"><xdr:graphicFrame macro=""><xdr:nvGraphicFramePr><xdr:cNvPr id="${frameId}" name="Chart ${frameId}"/><xdr:cNvGraphicFramePr/></xdr:nvGraphicFramePr><xdr:xfrm><a:off x="0" y="0"/><a:ext cx="${widthEmu}" cy="${heightEmu}"/></xdr:xfrm><a:graphic><a:graphicData uri="${CHART_EX_NS}"><cx:chart xmlns:cx="${CHART_EX_NS}" xmlns:r="${R_NS}" r:id="${relId}"/></a:graphicData></a:graphic></xdr:graphicFrame></mc:Choice></mc:AlternateContent>`;

package/dist/esm/exporter/xlsx/form-controls-builder.d.ts

@@ -0,0 +1,61 @@
+import type { EmbedFormControlSpec } from "@rowsncolumns/spreadsheet";
+/**
+ * Excel form-control writers — the inverse of
+ * `excel-parser/plugins/xlsx/form-controls.ts`. A control is three parts:
+ * the worksheet `<controls><control>` entry (anchor + `<controlPr>`), its
+ * `xl/ctrlProps/ctrlPropN.xml` (`<formControlPr>`), and the legacy VML shape
+ * Excel actually draws (`<v:shape type="#_x0000_t201"><x:ClientData
+ * ObjectType="Checkbox">`). All three are written; Excel drops a control
+ * whose VML shape is missing.
+ */
+export declare const CTRL_PROP_CONTENT_TYPE = "application/vnd.ms-excel.controlproperties+xml";
+export declare const CTRL_PROP_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp";
+export declare const FORM_CONTROL_NS = "http://schemas.microsoft.com/office/spreadsheetml/2009/9/main";
+/** `xl/ctrlProps/ctrlPropN.xml` body. */
+export declare const buildCtrlPropXml: (spec: EmbedFormControlSpec) => string;
+/** A cell anchor in OOXML units: 0-based cell + EMU offsets. */
+export type ControlCellAnchor = {
+    col: number;
+    colOff: number;
+    row: number;
+    rowOff: number;
+};
+/** One `<control>` element (inside the `<controls>` wrapper). */
+export declare const buildControlElementXml: ({ spec, relId, shapeId, from, to, }: {
+    spec: EmbedFormControlSpec;
+    relId: string;
+    shapeId: number;
+    from: ControlCellAnchor;
+    to: ControlCellAnchor;
+}) => string;
+/**
+ * The worksheet `<controls>` element. Excel wraps controls in an
+ * `mc:AlternateContent` whose `Choice` requires the `x14` namespace; the
+ * namespaces the wrapper and the `xdr:` anchor cells need are declared on
+ * the element so the worksheet root stays untouched.
+ */
+export declare const buildControlsXml: (controlElements: string[]) => string;
+/** VML `<v:shapetype>` every form control references (`#_x0000_t201`). */
+export declare const FORM_CONTROL_VML_SHAPETYPE = "<v:shapetype id=\"_x0000_t201\" coordsize=\"21600,21600\" o:spt=\"201\" path=\"m,l,21600r21600,l21600,xe\"><v:stroke joinstyle=\"miter\"/><v:path shadowok=\"f\" o:extrusionok=\"f\" strokeok=\"f\" fillok=\"f\" o:connecttype=\"rect\"/><o:lock v:ext=\"edit\" shapetype=\"t\"/></v:shapetype>";
+/** Pixel geometry the VML shape needs (absolute position + cell-span anchor). */
+export type FormControlVmlGeometry = {
+    leftPx: number;
+    topPx: number;
+    widthPx: number;
+    heightPx: number;
+    /** `x:Anchor` — from col, from col px offset, from row, from row px offset, to …  */
+    anchor: [number, number, number, number, number, number, number, number];
+};
+/** One `<v:shape>` drawing a form control. */
+export declare const buildFormControlVmlShape: ({ spec, shapeId, zIndex, geometry, }: {
+    spec: EmbedFormControlSpec;
+    shapeId: number;
+    zIndex: number;
+    geometry: FormControlVmlGeometry;
+}) => string;
+/** Wrap note + control shapes into one `vmlDrawing` part. */
+export declare const buildVmlDrawingXml: ({ shapeTypes, shapes, }: {
+    shapeTypes: string[];
+    shapes: string[];
+}) => string | undefined;
+//# sourceMappingURL=form-controls-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"form-controls-builder.d.ts","sourceRoot":"","sources":["../../../../exporter/xlsx/form-controls-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE;;;;;;;;GAQG;AAEH,eAAO,MAAM,sBAAsB,mDACe,CAAC;AACnD,eAAO,MAAM,kBAAkB,iFACiD,CAAC;AACjF,eAAO,MAAM,eAAe,kEACqC,CAAC;AAuBlE,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,GAAI,MAAM,oBAAoB,KAAG,MAU7D,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AASF,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,GAAI,qCAMpC;IACD,IAAI,EAAE,oBAAoB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,iBAAiB,CAAC;IACxB,EAAE,EAAE,iBAAiB,CAAC;CACvB,KAAG,MAaH,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,iBAAiB,MAAM,EAAE,KAAG,MAK5D,CAAC;AAmEF,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,oSAA4Q,CAAC;AAEpT,iFAAiF;AACjF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1E,CAAC;AAIF,8CAA8C;AAC9C,eAAO,MAAM,wBAAwB,GAAI,sCAKtC;IACD,IAAI,EAAE,oBAAoB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,sBAAsB,CAAC;CAClC,KAAG,MAmBH,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,kBAAkB,GAAI,yBAGhC;IACD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,KAAG,MAAM,GAAG,SAKZ,CAAC"}

package/dist/esm/exporter/xlsx/form-controls-builder.js

@@ -0,0 +1,173 @@
+/**
+ * Excel form-control writers — the inverse of
+ * `excel-parser/plugins/xlsx/form-controls.ts`. A control is three parts:
+ * the worksheet `<controls><control>` entry (anchor + `<controlPr>`), its
+ * `xl/ctrlProps/ctrlPropN.xml` (`<formControlPr>`), and the legacy VML shape
+ * Excel actually draws (`<v:shape type="#_x0000_t201"><x:ClientData
+ * ObjectType="Checkbox">`). All three are written; Excel drops a control
+ * whose VML shape is missing.
+ */
+export const CTRL_PROP_CONTENT_TYPE = "application/vnd.ms-excel.controlproperties+xml";
+export const CTRL_PROP_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp";
+export const FORM_CONTROL_NS = "http://schemas.microsoft.com/office/spreadsheetml/2009/9/main";
+const MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006";
+const XDR_NS = "http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing";
+const XML_DECLARATION = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n`;
+const escapeAttr = (value) => value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+const escapeText = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const attrsXml = (attrs) => Object.entries(attrs ?? {})
+    .filter(([key, value]) => key && value != null)
+    .map(([key, value]) => ` ${key}="${escapeAttr(String(value))}"`)
+    .join("");
+/** `xl/ctrlProps/ctrlPropN.xml` body. */
+export const buildCtrlPropXml = (spec) => {
+    const { objectType: _ignored, ...rest } = spec.properties ?? {};
+    const items = (spec.listItems ?? [])
+        .map((item) => `<item val="${escapeAttr(item)}"/>`)
+        .join("");
+    const body = items ? `<itemLst>${items}</itemLst>` : "";
+    const open = `<formControlPr xmlns="${FORM_CONTROL_NS}" objectType="${escapeAttr(spec.objectType)}"${attrsXml(rest)}`;
+    return `${XML_DECLARATION}${body ? `${open}>${body}</formControlPr>` : `${open}/>`}`;
+};
+const cellAnchorXml = (tag, anchor) => `<${tag}><xdr:col>${anchor.col}</xdr:col><xdr:colOff>${Math.round(anchor.colOff)}</xdr:colOff><xdr:row>${anchor.row}</xdr:row><xdr:rowOff>${Math.round(anchor.rowOff)}</xdr:rowOff></${tag}>`;
+/** One `<control>` element (inside the `<controls>` wrapper). */
+export const buildControlElementXml = ({ spec, relId, shapeId, from, to, }) => {
+    const name = spec.name ?? `${spec.objectType} ${shapeId}`;
+    const anchorAttrs = (spec.moveWithCells ? ' moveWithCells="1"' : "") +
+        (spec.sizeWithCells ? ' sizeWithCells="1"' : "");
+    return `<control shapeId="${shapeId}" r:id="${relId}" name="${escapeAttr(name)}"><controlPr${attrsXml(spec.controlProperties)}><anchor${anchorAttrs}>${cellAnchorXml("from", from)}${cellAnchorXml("to", to)}</anchor></controlPr></control>`;
+};
+/**
+ * The worksheet `<controls>` element. Excel wraps controls in an
+ * `mc:AlternateContent` whose `Choice` requires the `x14` namespace; the
+ * namespaces the wrapper and the `xdr:` anchor cells need are declared on
+ * the element so the worksheet root stays untouched.
+ */
+export const buildControlsXml = (controlElements) => {
+    if (!controlElements.length)
+        return "";
+    return `<controls xmlns:mc="${MC_NS}" xmlns:xdr="${XDR_NS}" xmlns:x14="${FORM_CONTROL_NS}"><mc:AlternateContent><mc:Choice Requires="x14">${controlElements.join("")}</mc:Choice></mc:AlternateContent></controls>`;
+};
+/** `formControlPr/@objectType` → VML `x:ClientData/@ObjectType`. */
+const VML_OBJECT_TYPE = {
+    CheckBox: "Checkbox",
+    EditBox: "Edit",
+};
+const truthy = (value) => value === "1" || value === "true";
+/**
+ * `x:ClientData` children derived from the `formControlPr` / `controlPr`
+ * attributes — Excel reads the control's state (checked, linked cell, list
+ * range, selection, scroll values) from the VML, the ctrlProp part is the
+ * x14 mirror.
+ */
+const clientDataChildrenXml = (spec) => {
+    const p = spec.properties ?? {};
+    const c = spec.controlProperties ?? {};
+    const out = [];
+    const push = (tag, value) => {
+        if (value === undefined)
+            out.push(`<x:${tag}/>`);
+        else
+            out.push(`<x:${tag}>${escapeText(value)}</x:${tag}>`);
+    };
+    if (spec.moveWithCells)
+        push("MoveWithCells");
+    if (spec.sizeWithCells)
+        push("SizeWithCells");
+    // Anchor is inserted by the caller (needs sheet geometry).
+    out.push("__ANCHOR__");
+    if (c.locked === "0")
+        push("Locked", "False");
+    if (c.defaultSize === "0")
+        push("DefaultSize", "False");
+    if (c.print === "0")
+        push("PrintObject", "False");
+    if (c.autoFill === "0")
+        push("AutoFill", "False");
+    if (c.autoLine === "0")
+        push("AutoLine", "False");
+    if (c.autoPict === "0")
+        push("AutoPict", "False");
+    if (c.macro)
+        push("FmlaMacro", c.macro);
+    if (p.textHAlign)
+        push("TextHAlign", p.textHAlign);
+    if (p.textVAlign)
+        push("TextVAlign", p.textVAlign);
+    if (truthy(p.lockText))
+        push("LockText");
+    if (truthy(p.justLastX))
+        push("JustLastX");
+    if (truthy(p.passwordEdit))
+        push("SecretEdit");
+    if (truthy(p.multiLine))
+        push("MultiLine");
+    if (truthy(p.verticalBar))
+        push("VScroll");
+    if (p.fmlaRange)
+        push("FmlaRange", p.fmlaRange);
+    if (p.widthMin)
+        push("WidthMin", p.widthMin);
+    if (p.sel)
+        push("Sel", p.sel);
+    if (p.seltype)
+        push("SelType", p.seltype);
+    if (p.multiSel)
+        push("MultiSel", p.multiSel);
+    if (p.dropStyle)
+        push("DropStyle", p.dropStyle);
+    if (truthy(p.colored))
+        push("Colored");
+    if (p.dropLines)
+        push("DropLines", p.dropLines);
+    if (p.checked === "Checked")
+        push("Checked", "1");
+    else if (p.checked === "Mixed")
+        push("Checked", "2");
+    if (p.fmlaLink)
+        push("FmlaLink", p.fmlaLink);
+    if (truthy(p.noThreeD))
+        push("NoThreeD");
+    if (truthy(p.firstButton))
+        push("FirstButton");
+    if (p.fmlaGroup)
+        push("FmlaGroup", p.fmlaGroup);
+    if (p.val)
+        push("Val", p.val);
+    if (p.min)
+        push("Min", p.min);
+    if (p.max)
+        push("Max", p.max);
+    if (p.inc)
+        push("Inc", p.inc);
+    if (p.page)
+        push("Page", p.page);
+    if (truthy(p.horiz))
+        push("Horiz");
+    if (p.dx)
+        push("Dx", p.dx);
+    return out.join("");
+};
+/** VML `<v:shapetype>` every form control references (`#_x0000_t201`). */
+export const FORM_CONTROL_VML_SHAPETYPE = `<v:shapetype id="_x0000_t201" coordsize="21600,21600" o:spt="201" path="m,l,21600r21600,l21600,xe"><v:stroke joinstyle="miter"/><v:path shadowok="f" o:extrusionok="f" strokeok="f" fillok="f" o:connecttype="rect"/><o:lock v:ext="edit" shapetype="t"/></v:shapetype>`;
+const toPt = (px) => `${(px * 0.75).toFixed(2).replace(/\.?0+$/, "")}pt`;
+/** One `<v:shape>` drawing a form control. */
+export const buildFormControlVmlShape = ({ spec, shapeId, zIndex, geometry, }) => {
+    const objectType = VML_OBJECT_TYPE[spec.objectType] ?? spec.objectType;
+    const caption = spec.text
+        ? `<div style="text-align:left"><font face="Tahoma" size="160" color="auto">${escapeText(spec.text)}</font></div>`
+        : "";
+    const clientData = clientDataChildrenXml(spec).replace("__ANCHOR__", `<x:Anchor>${geometry.anchor.join(", ")}</x:Anchor>`);
+    const style = `position:absolute;margin-left:${toPt(geometry.leftPx)};margin-top:${toPt(geometry.topPx)};width:${toPt(geometry.widthPx)};height:${toPt(geometry.heightPx)};z-index:${zIndex};mso-wrap-style:tight`;
+    return `<v:shape id="_x0000_s${shapeId}" type="#_x0000_t201" style="${style}" filled="f" fillcolor="window [65]" stroked="f" strokecolor="windowText [64]" o:insetmode="auto"><v:path shadowok="f" o:extrusionok="f" strokeok="f" fillok="f" o:connecttype="rect"/><v:textbox style="mso-direction-alt:auto" o:singleclick="f">${caption}</v:textbox><x:ClientData ObjectType="${escapeAttr(objectType)}">${clientData}</x:ClientData></v:shape>`;
+};
+/** Wrap note + control shapes into one `vmlDrawing` part. */
+export const buildVmlDrawingXml = ({ shapeTypes, shapes, }) => {
+    if (!shapes.length)
+        return undefined;
+    return `<xml xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:x="urn:schemas-microsoft-com:office:excel"><o:shapelayout v:ext="edit"><o:idmap v:ext="edit" data="1"/></o:shapelayout>${shapeTypes.join("")}${shapes.join("")}</xml>`;
+};

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

@@ -26,6 +26,14 @@
  * + ~100 lines in xlsx-export.ts) is the closest reference template.
  */
 import type { PivotTable } from "@rowsncolumns/spreadsheet";
+/**
+ * Distinct source fields a calculated-field formula references —
+ * single-quoted names (`'Unit Price'`, `''` escapes a quote) or bare
+ * identifiers; numeric literals (incl. `1e5`) and operators are skipped.
+ * Mirrors `@rowsncolumns/pivot`'s tokenizer without pulling in the
+ * DuckDB-backed pivot package.
+ */
+export declare const calculatedFieldReferences: (formula: string) => string[];
 /**
  * Build pivotCacheDefinition XML for a pivot. The cacheSource
  * points at the live worksheet range; `refreshOnLoad="1"` makes

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

@@ -1 +1 @@
-{"version":3,"file":"pivot-builder.d.ts","sourceRoot":"","sources":["../../../../exporter/xlsx/pivot-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AA4D5D;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACvC,OAAO,UAAU,EACjB,WAAW,MAAM,EACjB,YAAY,MAAM,EAAE,KACnB,MAAM,GAAG,IAgCX,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,UAAU,EACjB,SAAS,MAAM,EACf,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAChC,MAAM,GAAG,IAkHX,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU,MAAM,EAChB,aAAa,MAAM,KAClB,MAcF,CAAC"}
+{"version":3,"file":"pivot-builder.d.ts","sourceRoot":"","sources":["../../../../exporter/xlsx/pivot-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,2BAA2B,CAAC;AAqBxE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,MAAM,KAAG,MAAM,EAYjE,CAAC;AA2DF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACvC,OAAO,UAAU,EACjB,WAAW,MAAM,EACjB,YAAY,MAAM,EAAE,KACnB,MAAM,GAAG,IAuCX,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,UAAU,EACjB,SAAS,MAAM,EACf,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAChC,MAAM,GAAG,IA2JX,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU,MAAM,EAChB,aAAa,MAAM,KAClB,MAcF,CAAC"}