@rowsncolumns/toolkit 24.4.1 → 24.4.3

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

@@ -1492,6 +1492,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 +1508,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/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"}

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

@@ -1,4 +1,43 @@
 import { XMLBuilder } from "fast-xml-parser";
+/**
+ * `PivotValue.showAs` → `dataField@showDataAs` (ECMA-376) or, for the
+ * rank modes Excel only knows through its 2010 extension,
+ * `x14:dataField@pivotShowAs`.
+ */
+const SHOW_DATA_AS = {
+    pct_of_total: "percentOfTotal",
+    pct_of_row: "percentOfRow",
+    pct_of_column: "percentOfCol",
+    running_total: "runTotal",
+};
+const X14_PIVOT_SHOW_AS = {
+    rank_asc: "rankAscending",
+    rank_desc: "rankDescending",
+};
+const X14_DATA_FIELD_EXT_URI = "{E15A36E0-9728-4e99-A89B-3F7291B0FE68}";
+const X14_NS = "http://schemas.microsoft.com/office/spreadsheetml/2009/9/main";
+/**
+ * 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 const calculatedFieldReferences = (formula) => {
+    const out = [];
+    const push = (name) => {
+        if (name && !out.includes(name))
+            out.push(name);
+    };
+    const re = /'((?:[^']|'')*)'|(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?|([A-Za-z_\u00C0-\uFFFF][A-Za-z0-9_.\u00C0-\uFFFF]*)/g;
+    for (const m of formula.replace(/^\s*=/, "").matchAll(re)) {
+        if (m[1] !== undefined)
+            push(m[1].replace(/''/g, "'"));
+        else if (m[2] !== undefined)
+            push(m[2]);
+    }
+    return out;
+};
 const xmlBuilder = new XMLBuilder({
     ignoreAttributes: false,
     attributeNamePrefix: "@_",
@@ -54,10 +93,15 @@ export const buildPivotCacheDefinitionXml = (pivot, sheetName, fieldNames) => {
     if (!pivot.source)
         return null;
     const sourceRef = rangeRef(pivot.source);
-    const cacheFields = fieldNames.map((name) => ({
-        "@_name": name,
-        sharedItems: { "@_count": "0" },
-    }));
+    // Calculated fields are cache fields too (`databaseField="0"` +
+    // `formula`), listed after the source columns like Excel does.
+    const calculatedByName = new Map((pivot.calculatedFields ?? []).map((c) => [c.name, c.formula]));
+    const cacheFields = fieldNames.map((name) => {
+        const formula = calculatedByName.get(name);
+        return formula !== undefined
+            ? { "@_name": name, "@_formula": formula, "@_databaseField": "0" }
+            : { "@_name": name, sharedItems: { "@_count": "0" } };
+    });
     const doc = {
         "?xml": { "@_version": "1.0", "@_encoding": "UTF-8", "@_standalone": "yes" },
         pivotCacheDefinition: {
@@ -95,8 +139,10 @@ export const buildPivotTableXml = (pivot, cacheId, fieldIndices) => {
     if (!pivot.pivotRange)
         return null;
     const ref = rangeRef(pivot.pivotRange);
-    // pivotFields: one entry per cacheField, with axis attribute
-    // (axisRow / axisCol / dataField). Order = cacheField order.
+    // pivotFields: one entry per cacheField, with the axis attribute
+    // (axisRow / axisCol) and/or `dataField="1"` for value fields
+    // (`ST_Axis` has no "dataField" value — a field can sit on an axis
+    // AND be a data field). Order = cacheField order.
     const pivotFields = [];
     // We don't know the full field universe here without the source
     // schema. Best-effort: declare entries for the union of row/col/
@@ -112,23 +158,38 @@ export const buildPivotTableXml = (pivot, cacheId, fieldIndices) => {
         if (idx != null)
             fieldAxis.set(idx, "axisCol");
     }
+    const dataFieldIndices = new Set();
     for (const v of pivot.values ?? []) {
         const idx = fieldIndices.get(v.field);
         if (idx != null)
-            fieldAxis.set(idx, "dataField");
+            dataFieldIndices.add(idx);
     }
+    const calculatedNames = new Set((pivot.calculatedFields ?? []).map((c) => c.name));
     // Need to emit one <pivotField> per cacheField in order, even
     // for unused fields (Excel requires the array shapes match).
     // Caller passes us the full field set via fieldIndices.
     const sortedFieldIndices = [...fieldIndices.entries()].sort((a, b) => a[1] - b[1]);
-    for (const [, idx] of sortedFieldIndices) {
+    for (const [name, idx] of sortedFieldIndices) {
         const axis = fieldAxis.get(idx);
-        if (axis) {
-            pivotFields.push({ "@_axis": axis, "@_compact": "0", items: {} });
+        const entry = {};
+        if (axis)
+            entry["@_axis"] = axis;
+        if (dataFieldIndices.has(idx))
+            entry["@_dataField"] = "1";
+        if (calculatedNames.has(name)) {
+            // Excel pins calculated fields to the values area.
+            entry["@_dragToRow"] = "0";
+            entry["@_dragToCol"] = "0";
+            entry["@_dragToPage"] = "0";
+            entry["@_showAll"] = "0";
+            entry["@_defaultSubtotal"] = "0";
         }
         else {
-            pivotFields.push({ "@_compact": "0" });
+            entry["@_compact"] = "0";
+            if (axis)
+                entry.items = {};
         }
+        pivotFields.push(entry);
     }
     const rowFields = (pivot.rows ?? [])
         .map((r) => fieldIndices.get(r.field))
@@ -138,18 +199,42 @@ export const buildPivotTableXml = (pivot, cacheId, fieldIndices) => {
         .map((c) => fieldIndices.get(c.field))
         .filter((i) => i != null)
         .map((i) => ({ "@_x": String(i) }));
+    // Running totals need a base field: Excel defaults to the first row
+    // field (falls back to the first column field / field 0).
+    const runTotalBase = rowFields[0]?.["@_x"] ?? colFields[0]?.["@_x"] ?? "0";
     const dataFields = (pivot.values ?? [])
         .map((v) => {
         const idx = fieldIndices.get(v.field);
         if (idx == null)
             return null;
-        return {
+        const entry = {
             "@_name": v.displayName ?? `${v.aggFunc} of ${v.field}`,
             "@_fld": String(idx),
-            "@_subtotal": aggToSubtotal(v.aggFunc),
+            "@_subtotal": calculatedNames.has(v.field)
+                ? "sum"
+                : aggToSubtotal(v.aggFunc),
         };
+        const showDataAs = v.showAs ? SHOW_DATA_AS[v.showAs] : undefined;
+        if (showDataAs) {
+            entry["@_showDataAs"] = showDataAs;
+            if (showDataAs === "runTotal")
+                entry["@_baseField"] = runTotalBase;
+        }
+        const pivotShowAs = v.showAs ? X14_PIVOT_SHOW_AS[v.showAs] : undefined;
+        if (pivotShowAs) {
+            entry.extLst = {
+                ext: {
+                    "@_uri": X14_DATA_FIELD_EXT_URI,
+                    "@_xmlns:x14": X14_NS,
+                    "x14:dataField": { "@_pivotShowAs": pivotShowAs },
+                },
+            };
+        }
+        return entry;
     })
         .filter((d) => d !== null);
+    const styleInfo = pivot.styleInfo ?? {};
+    const styleFlag = (value, fallback) => value === undefined ? fallback : value ? "1" : "0";
     const doc = {
         "?xml": { "@_version": "1.0", "@_encoding": "UTF-8", "@_standalone": "yes" },
         pivotTableDefinition: {
@@ -195,12 +280,12 @@ export const buildPivotTableXml = (pivot, cacheId, fieldIndices) => {
                 ? { "@_count": String(dataFields.length), dataField: dataFields }
                 : undefined,
             pivotTableStyleInfo: {
-                "@_name": "PivotStyleLight16",
-                "@_showRowHeaders": "1",
-                "@_showColHeaders": "1",
-                "@_showRowStripes": "0",
-                "@_showColStripes": "0",
-                "@_showLastColumn": "1",
+                "@_name": styleInfo.name || "PivotStyleLight16",
+                "@_showRowHeaders": styleFlag(styleInfo.showRowHeaders, "1"),
+                "@_showColHeaders": styleFlag(styleInfo.showColHeaders, "1"),
+                "@_showRowStripes": styleFlag(styleInfo.showRowStripes, "0"),
+                "@_showColStripes": styleFlag(styleInfo.showColStripes, "0"),
+                "@_showLastColumn": styleFlag(styleInfo.showLastColumn, "1"),
             },
         },
     };

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

@@ -702,10 +702,16 @@ const serializeAlignment = (record) => {
         attrs.push(`relativeIndent="${record.relativeIndent}"`);
     }
     if (record.textRotation !== undefined && record.textRotation !== null) {
-        // Excel encodes "vertical (stacked)" text as the magic value 255.
-        const rotation = record.textRotation === "vertical" ? 255 : record.textRotation;
+        // Excel encodes "vertical (stacked)" text as the magic value 255 and
+        // clockwise rotation as 90 + degrees (91–180); the engine keeps signed
+        // counter-clockwise degrees.
+        const rotation = record.textRotation === "vertical"
+            ? 255
+            : record.textRotation < 0
+                ? 90 - record.textRotation
+                : record.textRotation;
         if (Number.isFinite(rotation) && rotation !== 0) {
-            attrs.push(`textRotation="${rotation}"`);
+            attrs.push(`textRotation="${Math.round(rotation)}"`);
         }
     }
     if (record.shrinkToFit) {

package/dist/esm/exporter/xlsx/threaded-comments-builder.d.ts

@@ -10,6 +10,7 @@ export declare const PERSON_CONTENT_TYPE = "application/vnd.ms-excel.person+xml"
  * scoping author/comment ids within a single workbook.
  */
 export declare const deterministicGuid: (seed: string) => string;
+export declare const isBracedGuid: (id: string) => boolean;
 /**
  * Workbook-scoped author registry. Shared across every sheet's collector so
  * an author who comments on multiple sheets maps to a single `person` entry
@@ -35,7 +36,12 @@ export declare class ThreadedCommentsCollector {
     /** Anchor a thread to a cell. No-op if the id is unknown or empty. */
     addCell(address: string, threadId: string | number | null | undefined): void;
     isEmpty(): boolean;
-    /** Braced root GUID for a thread — used as both the root `id` and `tc=`. */
+    /**
+     * Braced root GUID for a thread — used as both the root `id` and `tc=`.
+     * An id that already is a braced GUID (what Excel and both importers
+     * produce) passes through, so a re-exported thread keeps the identity
+     * Excel assigned it; anything else is hashed deterministically.
+     */
     private rootGuid;
     /**
      * Legacy `xl/comments{N}.xml` mirror entries. Feed these into the existing

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

@@ -1 +1 @@
-{"version":3,"file":"threaded-comments-builder.d.ts","sourceRoot":"","sources":["../../../../exporter/xlsx/threaded-comments-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAyBhE,eAAO,MAAM,yBAAyB,8EACuC,CAAC;AAC9E,eAAO,MAAM,eAAe,qEACwC,CAAC;AACrE,eAAO,MAAM,8BAA8B,kDACM,CAAC;AAClD,eAAO,MAAM,mBAAmB,wCAAwC,CAAC;AAsBzE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MAiBhD,CAAC;AAEF;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGlB;IAEJ,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS;IAWtE,OAAO;IAIP,KAAK;CAYN;AAQD;;;;GAIG;AACH,qBAAa,yBAAyB;IAMlC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;gBAG3C,OAAO,EAAE,aAAa,EAAE,GAAG,SAAS,EACnB,OAAO,EAAE,cAAc;IAO1C,sEAAsE;IACtE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS;IAQrE,OAAO;IAIP,4EAA4E;IAC5E,OAAO,CAAC,QAAQ;IAIhB;;;;;OAKG;IACH,aAAa,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE;IAcpE;;;;OAIG;IACH,KAAK,IAAI,MAAM,GAAG,SAAS;CA+B5B"}
+{"version":3,"file":"threaded-comments-builder.d.ts","sourceRoot":"","sources":["../../../../exporter/xlsx/threaded-comments-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAyBhE,eAAO,MAAM,yBAAyB,8EACuC,CAAC;AAC9E,eAAO,MAAM,eAAe,qEACwC,CAAC;AACrE,eAAO,MAAM,8BAA8B,kDACM,CAAC;AAClD,eAAO,MAAM,mBAAmB,wCAAwC,CAAC;AAsBzE;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MAiBhD,CAAC;AAKF,eAAO,MAAM,YAAY,GAAI,IAAI,MAAM,YAAyB,CAAC;AAEjE;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGlB;IAEJ,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS;IAWtE,OAAO;IAIP,KAAK;CAYN;AAQD;;;;GAIG;AACH,qBAAa,yBAAyB;IAMlC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;gBAG3C,OAAO,EAAE,aAAa,EAAE,GAAG,SAAS,EACnB,OAAO,EAAE,cAAc;IAO1C,sEAAsE;IACtE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS;IAQrE,OAAO;IAIP;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAMhB;;;;;OAKG;IACH,aAAa,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE;IAcpE;;;;OAIG;IACH,KAAK,IAAI,MAAM,GAAG,SAAS;CAiC5B"}

package/dist/esm/exporter/xlsx/threaded-comments-builder.js

@@ -60,6 +60,9 @@ export const deterministicGuid = (seed) => {
     const p5 = all.slice(20, 32);
     return `{${p1}-${p2}-${p3}-${p4}-${p5}}`;
 };
+/** `{8-4-4-4-12}` hex, the braced RFC-4122 form Excel writes for comment and person ids. */
+const BRACED_GUID = /^\{[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}\}$/;
+export const isBracedGuid = (id) => BRACED_GUID.test(id);
 /**
  * Workbook-scoped author registry. Shared across every sheet's collector so
  * an author who comments on multiple sheets maps to a single `person` entry
@@ -118,9 +121,16 @@ export class ThreadedCommentsCollector {
     isEmpty() {
         return this.placed.length === 0;
     }
-    /** Braced root GUID for a thread — used as both the root `id` and `tc=`. */
+    /**
+     * Braced root GUID for a thread — used as both the root `id` and `tc=`.
+     * An id that already is a braced GUID (what Excel and both importers
+     * produce) passes through, so a re-exported thread keeps the identity
+     * Excel assigned it; anything else is hashed deterministically.
+     */
     rootGuid(thread) {
-        return deterministicGuid(`tc:${thread.id}`);
+        return isBracedGuid(thread.id)
+            ? thread.id.toUpperCase()
+            : deterministicGuid(`tc:${thread.id}`);
     }
     /**
      * Legacy `xl/comments{N}.xml` mirror entries. Feed these into the existing
@@ -157,7 +167,9 @@ export class ThreadedCommentsCollector {
                 const personId = this.persons.register(msg.authorId, msg.authorName);
                 const id = index === 0
                     ? root
-                    : deterministicGuid(`c:${thread.id}:${msg.id}`);
+                    : isBracedGuid(msg.id)
+                        ? msg.id.toUpperCase()
+                        : deterministicGuid(`c:${thread.id}:${msg.id}`);
                 const parent = index === 0 ? "" : ` parentId="${root}"`;
                 // Resolved state rides on the root as `done="1"` (MS-XLSX);
                 // replies never carry it.

package/dist/esm/exporter/xlsx/xlsx-export.d.ts

@@ -1,5 +1,5 @@
 import type { CellData, Citation, CommentThread, DataValidationRuleRecord, IterativeCalculationOptions, SheetData, TextFormat } from "@rowsncolumns/common-types";
-import type { Color, ConditionalFormatRule, EmbeddedChart, EmbeddedObject, NamedRange, PivotTable, Sheet, Slicer, SpreadsheetTheme, TableView } from "@rowsncolumns/spreadsheet";
+import type { Color, ConditionalFormatRule, EmbeddedChart, EmbeddedObject, NamedRange, PivotTable, ProtectedRange, Sheet, Slicer, SpreadsheetTheme, TableView } from "@rowsncolumns/spreadsheet";
 import type { CellXfs, SharedStrings as SharedStringsType } from "@rowsncolumns/spreadsheet-state";
 import type { PowerQueryParts } from "../../power-query";
 import type { ExternalLink, WorkbookProperties } from "../../excel-parser/types";
@@ -32,6 +32,15 @@ export type ExportExcelProps<S extends Sheet, T extends CellData, C extends Cita
     pivotTables?: PivotTable[];
     externalLinks?: ExternalLink[];
     namedRanges?: NamedRange[];
+    /**
+     * Allow-edit ranges (`useSpreadsheetState`'s `protectedRanges`), written as
+     * `<protectedRanges>/<protectedRange sqref name>` on the sheet each range's
+     * `range.sheetId` names. Sheet-level protection is read from
+     * `Sheet.sheetProtection` and written as `<sheetProtection …>`; both sit
+     * right after `<sheetData>` per `CT_Worksheet`, the position the parser and
+     * `rnc-import` read them back from.
+     */
+    protectedRanges?: ProtectedRange[];
     /**
      * Workbook-wide named cell styles to round-trip into the
      * `<cellStyles>` block of styles.xml. Parsed by the importer as
@@ -109,7 +118,7 @@ export type ExportExcelProps<S extends Sheet, T extends CellData, C extends Cita
      */
     properties?: WorkbookProperties;
 };
-export declare const createExcelFile: <S extends Sheet, T extends CellData, C extends Citation>({ conditionalFormats: _conditionalFormats, dataValidations: _dataValidations, sheets, sheetData, sharedStrings: sourceSharedStrings, tables: _tables, cellXfs, theme, defaultFont, embeds, charts, slicers, pivotTables, externalLinks, namedRanges, namedCellStyles, customTableStyles, iterativeCalculationOptions, ignoreFormulaPatterns, citations, comments, password, locale, use1904, properties, powerQuery, }: ExportExcelProps<S, T, C>) => Promise<Uint8Array<ArrayBufferLike>>;
+export declare const createExcelFile: <S extends Sheet, T extends CellData, C extends Citation>({ conditionalFormats: _conditionalFormats, dataValidations: _dataValidations, sheets, sheetData, sharedStrings: sourceSharedStrings, tables: _tables, cellXfs, theme, defaultFont, embeds, charts, slicers, pivotTables, externalLinks, namedRanges, protectedRanges, namedCellStyles, customTableStyles, iterativeCalculationOptions, ignoreFormulaPatterns, citations, comments, password, locale, use1904, properties, powerQuery, }: ExportExcelProps<S, T, C>) => Promise<Uint8Array<ArrayBufferLike>>;
 /**
  * Normalize a dataValidation sqref list: collapse degenerate ranges
  * (`C7:C7` → `C7`), drop exact duplicates, and drop members fully contained

package/dist/esm/exporter/xlsx/xlsx-export.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xlsx-export.d.ts","sourceRoot":"","sources":["../../../../exporter/xlsx/xlsx-export.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"xlsx-export.d.ts","sourceRoot":"","sources":["../../../../exporter/xlsx/xlsx-export.ts"],"names":[],"mappings":"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"}