@rowsncolumns/toolkit 24.4.2 → 24.4.4

package/dist/esm/excel-parser/plugins/xlsx/chartex.js

@@ -0,0 +1,199 @@
+import { generateSelectionsFromFormula, uuid } from "@rowsncolumns/utils";
+import { get } from "lodash-es";
+import { extractChartPosition, } from "./charts";
+/**
+ * Excel 2016+ "chartex" charts (`xl/charts/chartEx{N}.xml`, namespace
+ * `http://schemas.microsoft.com/office/drawing/2014/chartex`): treemap,
+ * sunburst, histogram / pareto, box & whisker, waterfall, funnel. They are
+ * anchored through an `mc:AlternateContent` whose `Choice` graphic frame
+ * carries `<cx:chart r:id>` instead of `<c:chart>`, and their data lives in
+ * `<cx:chartData><cx:data>` dimensions (`strDim type="cat"` for the
+ * hierarchy, `numDim type="size"|"val"` for the numbers) referenced by the
+ * series through `<cx:dataId>`.
+ *
+ * The exporter counterpart is `exporter/xlsx/chartex-builder.ts`.
+ */
+export const CHART_EX_REL_TYPE = "http://schemas.microsoft.com/office/2014/relationships/chartEx";
+export const CHART_EX_GRAPHIC_URI = "http://schemas.microsoft.com/office/drawing/2014/chartex";
+const asArray = (value) => value == null ? [] : Array.isArray(value) ? value : [value];
+/** Read a child by local name, tolerating any namespace prefix. */
+const child = (node, localName) => {
+    if (!node || typeof node !== "object")
+        return undefined;
+    if (node[localName] !== undefined)
+        return node[localName];
+    for (const key of Object.keys(node)) {
+        const colon = key.indexOf(":");
+        if (colon >= 0 && key.slice(colon + 1) === localName)
+            return node[key];
+    }
+    return undefined;
+};
+const textOf = (node) => {
+    if (node == null)
+        return undefined;
+    if (typeof node === "object") {
+        const inner = node.t$;
+        return inner == null ? undefined : String(inner);
+    }
+    return String(node);
+};
+/**
+ * `<cx:chart r:id>` inside an anchor's `mc:AlternateContent` choice (Excel
+ * also writes a plain `xdr:graphicFrame` for some producers — both forms are
+ * checked). Returns the `cx:chart` node or undefined for non-chartex anchors.
+ */
+export function getChartExReferenceFromAnchor(anchor) {
+    const frames = [];
+    for (const alternate of asArray(child(anchor, "AlternateContent"))) {
+        for (const choice of asArray(child(alternate, "Choice"))) {
+            frames.push(...asArray(child(choice, "graphicFrame")));
+        }
+    }
+    frames.push(...asArray(child(anchor, "graphicFrame")));
+    for (const frame of frames) {
+        const graphicData = child(child(frame, "graphic"), "graphicData");
+        if (!graphicData)
+            continue;
+        const uri = get(graphicData, "a$.uri");
+        const cxChart = child(graphicData, "chart");
+        if (uri === CHART_EX_GRAPHIC_URI && cxChart)
+            return cxChart;
+        // A `cx:`-prefixed chart element without the uri attribute (defensive).
+        if (cxChart && Object.keys(graphicData).some((k) => k.startsWith("cx:"))) {
+            return cxChart;
+        }
+    }
+    return undefined;
+}
+/** `layoutId` → engine chart type. Unknown layouts are not imported. */
+const CHART_TYPE_BY_LAYOUT = {
+    treemap: "treemap",
+    sunburst: "sunburst",
+    waterfall: "waterfall",
+    funnel: "funnel",
+    boxWhisker: "boxplot",
+    // `clusteredColumn` is a histogram / pareto only when it carries `<cx:binning>`.
+};
+const sourcesFromRef = (ref, hostSheetId, resolveSheetId) => {
+    if (!ref)
+        return [];
+    const selections = generateSelectionsFromFormula(`=${ref}`);
+    return selections.map((sel) => ({
+        ...sel.range,
+        sheetId: (sel.sheetName ? resolveSheetId?.(sel.sheetName) : undefined) ??
+            hostSheetId,
+    }));
+};
+const chartData = (sources) => ({ sources });
+/**
+ * Split a multi-column hierarchy range (Excel lays the treemap hierarchy out
+ * as columns, top level first, leaf last) into `parentLabels` (one entry per
+ * parent column) and `labels` (the leaf column).
+ */
+export const splitHierarchyRange = (range) => {
+    const parentLabels = [];
+    for (let c = range.startColumnIndex; c < range.endColumnIndex; c++) {
+        parentLabels.push({ ...range, startColumnIndex: c, endColumnIndex: c });
+    }
+    return {
+        parentLabels,
+        labels: {
+            ...range,
+            startColumnIndex: range.endColumnIndex,
+            endColumnIndex: range.endColumnIndex,
+        },
+    };
+};
+const dimensionRef = (data, dimTag, type) => {
+    const dims = asArray(child(data, dimTag)).filter((dim) => get(dim, "a$.type") === type);
+    const dim = dims[0] ?? (dimTag === "numDim" ? asArray(child(data, dimTag))[0] : undefined);
+    const f = child(dim, "f");
+    return textOf(Array.isArray(f) ? f[0] : f)?.trim() || undefined;
+};
+/** Parse a `cx:chartSpace` DOM into an `EmbeddedChart` spec (null when unsupported). */
+export function parseChartExSpec(chartSpaceDom, sheetId, resolveSheetId) {
+    const chartSpace = child(chartSpaceDom, "chartSpace") ?? chartSpaceDom;
+    const chart = child(chartSpace, "chart");
+    if (!chart)
+        return null;
+    const region = child(child(chart, "plotArea"), "plotAreaRegion");
+    const series = asArray(child(region, "series"))[0];
+    if (!series)
+        return null;
+    const layoutId = String(get(series, "a$.layoutId") ?? "");
+    // Excel nests `<cx:binning>` in `<cx:layoutPr>`; tolerate it directly on the series too.
+    const binning = child(child(series, "layoutPr"), "binning") ?? child(series, "binning");
+    const chartType = layoutId === "clusteredColumn" && binning
+        ? "histogram"
+        : CHART_TYPE_BY_LAYOUT[layoutId];
+    if (!chartType)
+        return null;
+    const dataId = String(get(child(series, "dataId"), "a$.val") ?? "0");
+    const data = asArray(child(child(chartSpace, "chartData"), "data")).find((d) => String(get(d, "a$.id")) === dataId) ?? asArray(child(child(chartSpace, "chartData"), "data"))[0];
+    if (!data)
+        return null;
+    const title = textOf(child(child(child(child(chart, "title"), "tx"), "txData"), "v"));
+    const catRef = dimensionRef(data, "strDim", "cat");
+    const catSources = sourcesFromRef(catRef, sheetId, resolveSheetId);
+    if (chartType === "treemap" || chartType === "sunburst") {
+        const sizeRef = dimensionRef(data, "numDim", "size");
+        const sizeSources = sourcesFromRef(sizeRef, sheetId, resolveSheetId);
+        if (!catSources.length || !sizeSources.length)
+            return null;
+        const hierarchy = splitHierarchyRange(catSources[0]);
+        return {
+            chartType,
+            ...(title ? { title } : {}),
+            labels: [chartData([hierarchy.labels])],
+            parentLabels: hierarchy.parentLabels.map((range) => chartData([range])),
+            sizeData: [chartData(sizeSources)],
+        };
+    }
+    const valRef = dimensionRef(data, "numDim", "val");
+    const valSources = sourcesFromRef(valRef, sheetId, resolveSheetId);
+    if (!valSources.length)
+        return null;
+    const spec = {
+        chartType,
+        ...(title ? { title } : {}),
+        series: [chartData(valSources)],
+        ...(catSources.length ? { domains: [chartData(catSources)] } : {}),
+    };
+    if (chartType === "histogram") {
+        const binCount = Number(get(child(binning, "binCount"), "a$.val"));
+        if (Number.isFinite(binCount) && binCount > 0)
+            spec.binCount = binCount;
+    }
+    return spec;
+}
+/** Resolve + parse one chartex part referenced from a drawing anchor. */
+export async function processChartEx(chartTarget, drawingPath, anchor, sheetId, zipParser, xmlParser, sheetDimensions, resolveSheetId) {
+    let chartPath = chartTarget;
+    const drawingDir = drawingPath.substring(0, drawingPath.lastIndexOf("/"));
+    if (chartPath.startsWith("/")) {
+        chartPath = chartPath.slice(1);
+    }
+    else if (chartPath.startsWith("../")) {
+        chartPath = `xl/${chartPath.replace("../", "")}`;
+    }
+    else if (!chartPath.startsWith("xl/")) {
+        chartPath = `${drawingDir}/${chartPath}`;
+    }
+    let content;
+    try {
+        content = await zipParser.getText(chartPath);
+    }
+    catch {
+        return null;
+    }
+    if (!content)
+        return null;
+    const spec = parseChartExSpec(xmlParser.parse(content), sheetId, resolveSheetId);
+    if (!spec)
+        return null;
+    const position = extractChartPosition(anchor, sheetId, sheetDimensions);
+    if (!position)
+        return null;
+    return { chartId: uuid(), spec, position };
+}

package/dist/esm/excel-parser/plugins/xlsx/charts.d.ts

@@ -17,6 +17,16 @@ export declare function extractChartDataRange(plotArea: any, chartType: string,
 export declare function extractHiddenDimensionStrategy(chart: any): HIDDEN_DIMENSION_STRATEGY | undefined;
 export declare function extractChartTitle(chart: any): string;
 export declare function determineChartType(chart: any): "bar" | "column" | "line" | "pie" | "doughnut" | "area" | "radar" | "stock" | "scatter" | "bubble" | "treemap" | "sunburst" | "histogram" | "boxplot" | "waterfall" | "funnel";
+/**
+ * The authored 3-D / surface chart class, when the plot area's chart
+ * element is one of Excel's 3-D variants. These degrade to their 2-D
+ * `chartType` (bar3DChart → bar/column, line3DChart → line, pie3DChart →
+ * pie, area3DChart / surfaceChart / surface3DChart → area) and the
+ * original class is preserved verbatim as `sourceChartType`, matching the
+ * Rust importer, so the renderer's echarts-gl pipeline and the exporter's
+ * 3-D writer can restore it. Undefined for plain 2-D charts.
+ */
+export declare function extractThreeDSourceChartType(plotArea: any): "BAR_3D" | "LINE_3D" | "PIE_3D" | "AREA_3D" | "SURFACE" | "SURFACE_3D" | undefined;
 /**
  * Phase 5.5 — pull binCount out of the c15:histogramChart extension
  * marker. Returns undefined if absent.

package/dist/esm/excel-parser/plugins/xlsx/charts.d.ts.map

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

package/dist/esm/excel-parser/plugins/xlsx/charts.js

@@ -120,6 +120,10 @@ export async function processChart(chartTarget, drawingPath, anchor, sheetId, zi
         // "pie" with sourceChartType "OF_PIE" plus the split fields the
         // renderer uses to draw the composite layout.
         const ofPieOptions = chartType === "pie" ? extractOfPieOptions(plotArea) : undefined;
+        // 3-D / surface variants — preserved as sourceChartType (BAR_3D,
+        // LINE_3D, PIE_3D, AREA_3D, SURFACE, SURFACE_3D) on top of the 2-D
+        // chartType they degrade to. Disjoint from OF_PIE.
+        const threeDSourceChartType = extractThreeDSourceChartType(plotArea);
         const radarStyle = chartType === "radar" ? extractRadarStyle(plotArea) : undefined;
         const binCount = chartType === "histogram"
             ? extractC15HistogramBinCount(plotArea)
@@ -166,6 +170,9 @@ export async function processChart(chartTarget, drawingPath, anchor, sheetId, zi
                 ...(ofPieOptions
                     ? { sourceChartType: "OF_PIE", ...ofPieOptions }
                     : {}),
+                ...(threeDSourceChartType && !ofPieOptions
+                    ? { sourceChartType: threeDSourceChartType }
+                    : {}),
                 ...(radarStyle ? { radarStyle } : {}),
                 ...(typeof binCount === "number" ? { binCount } : {}),
                 ...(barLayout?.stackedType
@@ -240,6 +247,12 @@ function getSeriesElements(plotArea, chartType) {
                 "areaChart.ser",
                 "c:area3DChart.c:ser",
                 "area3DChart.ser",
+                // Surface / contour charts degrade to area (sourceChartType
+                // SURFACE / SURFACE_3D); their series carry the same cat/val shape.
+                "c:surfaceChart.c:ser",
+                "surfaceChart.ser",
+                "c:surface3DChart.c:ser",
+                "surface3DChart.ser",
             ]);
         case "radar":
             return getWithFallback(plotArea, ["c:radarChart.c:ser", "radarChart.ser"]);
@@ -562,6 +575,12 @@ export function determineChartType(chart) {
         "areaChart",
         "c:area3DChart",
         "area3DChart",
+        // Surface / contour degrade to area — the same 2-D base the Rust
+        // importer and the renderer's surface pipeline use.
+        "c:surfaceChart",
+        "surfaceChart",
+        "c:surface3DChart",
+        "surface3DChart",
     ]))
         return "area";
     if (getWithFallback(plotArea, ["c:radarChart", "radarChart"]))
@@ -576,6 +595,31 @@ export function determineChartType(chart) {
         return "bubble";
     return "column"; // default
 }
+/**
+ * The authored 3-D / surface chart class, when the plot area's chart
+ * element is one of Excel's 3-D variants. These degrade to their 2-D
+ * `chartType` (bar3DChart → bar/column, line3DChart → line, pie3DChart →
+ * pie, area3DChart / surfaceChart / surface3DChart → area) and the
+ * original class is preserved verbatim as `sourceChartType`, matching the
+ * Rust importer, so the renderer's echarts-gl pipeline and the exporter's
+ * 3-D writer can restore it. Undefined for plain 2-D charts.
+ */
+export function extractThreeDSourceChartType(plotArea) {
+    const has = (paths) => Boolean(getWithFallback(plotArea, paths));
+    if (has(["c:bar3DChart", "bar3DChart"]))
+        return "BAR_3D";
+    if (has(["c:line3DChart", "line3DChart"]))
+        return "LINE_3D";
+    if (has(["c:pie3DChart", "pie3DChart"]))
+        return "PIE_3D";
+    if (has(["c:area3DChart", "area3DChart"]))
+        return "AREA_3D";
+    if (has(["c:surface3DChart", "surface3DChart"]))
+        return "SURFACE_3D";
+    if (has(["c:surfaceChart", "surfaceChart"]))
+        return "SURFACE";
+    return undefined;
+}
 /**
  * Phase 5.5 — detect the c15 extension marker our exporter writes on
  * the plotArea. Returns the originating chart type (histogram /
@@ -711,7 +755,16 @@ const CHART_TYPE_CONTAINERS = [
         chartType: "line",
     },
     {
-        paths: ["c:areaChart", "areaChart", "c:area3DChart", "area3DChart"],
+        paths: [
+            "c:areaChart",
+            "areaChart",
+            "c:area3DChart",
+            "area3DChart",
+            "c:surfaceChart",
+            "surfaceChart",
+            "c:surface3DChart",
+            "surface3DChart",
+        ],
         chartType: "area",
     },
     {
@@ -1765,13 +1818,23 @@ const mapDataLabelPosition = (val) => {
 function extractDataLabelsOptions(plotArea, chartType) {
     // Look for <c:dLbls> inside the chartType-specific container. We pick
     // the first one we find — chart-level labels apply to all series.
+    // The 3-D classes (bar3DChart / line3DChart / pie3DChart / area3DChart)
+    // degrade to the same `chartType` and carry `<c:dLbls>` in the same slot
+    // of their group, so they are looked up alongside the 2-D container.
     const containerKeys = {
-        bar: ["c:barChart", "barChart"],
-        column: ["c:barChart", "barChart"],
-        line: ["c:lineChart", "lineChart"],
-        pie: ["c:pieChart", "pieChart", "c:ofPieChart", "ofPieChart"],
+        bar: ["c:barChart", "barChart", "c:bar3DChart", "bar3DChart"],
+        column: ["c:barChart", "barChart", "c:bar3DChart", "bar3DChart"],
+        line: ["c:lineChart", "lineChart", "c:line3DChart", "line3DChart"],
+        pie: [
+            "c:pieChart",
+            "pieChart",
+            "c:ofPieChart",
+            "ofPieChart",
+            "c:pie3DChart",
+            "pie3DChart",
+        ],
         doughnut: ["c:doughnutChart", "doughnutChart"],
-        area: ["c:areaChart", "areaChart"],
+        area: ["c:areaChart", "areaChart", "c:area3DChart", "area3DChart"],
     };
     const keys = containerKeys[chartType] ?? [];
     let container;

package/dist/esm/excel-parser/plugins/xlsx/drawing.d.ts

@@ -1,9 +1,28 @@
-import type { EmbeddedObject, EmbedShapeSpec } from "@rowsncolumns/spreadsheet";
+import type { EmbeddedObject, EmbedImageSpec, EmbedShapeSpec } from "@rowsncolumns/spreadsheet";
 import { type XMLParser } from "fast-xml-parser";
 import { type StreamingZipParser } from "../../zip-parser-streaming";
 export type EmbeddedObjectWithPosition = EmbeddedObject & {
     isInsideCell?: boolean;
 };
+/** `processAnchors` anchor-type tags, keyed by the drawing element name. */
+declare const ANCHOR_KIND_BY_ELEMENT: {
+    readonly oneCellAnchor: "oneCellAnchor";
+    readonly twoCellAnchor: "twoCellAnchors";
+    readonly absoluteAnchor: "absoluteAnchors";
+};
+type AnchorElementName = keyof typeof ANCHOR_KIND_BY_ELEMENT;
+/**
+ * The `<xdr:wsDr>` anchors in document order — Excel's z-order (first is
+ * the back-most object). The unordered parse keeps document order within one
+ * element name but groups the three anchor kinds apart, so the kind sequence
+ * is read off the raw part and the parsed nodes are dealt out in that order.
+ * Anchors the scan does not account for (namespace quirks) trail in their
+ * parsed order, so nothing is ever dropped.
+ */
+export declare function anchorsInDocumentOrder(drawing: any, drawingXml: string): Array<{
+    kind: (typeof ANCHOR_KIND_BY_ELEMENT)[AnchorElementName];
+    node: any;
+}>;
 /**
  * Process different types of image anchors
  * @param anchors The anchor elements from the drawing
@@ -15,6 +34,13 @@ export type EmbeddedObjectWithPosition = EmbeddedObject & {
  * @returns An array of image objects with their properties and binary data
  */
 export declare function processAnchors(anchors: any, anchorType: string, drawingPath: string, sheetId: number, zipParser: StreamingZipParser, xmlParser: XMLParser): Promise<EmbeddedObjectWithPosition[]>;
+/**
+ * Picture-format adjustments off an `<xdr:pic>`: `<a:blipFill><a:srcRect>`
+ * (crop), `<a:blip><a:lum bright contrast>` (brightness / contrast) and
+ * `<a:blip><a:alphaModFix amt>` (opacity → `transparency`). Only present
+ * values are returned so an untouched picture stays a bare image spec.
+ */
+export declare function parsePictureAdjustments(picture: any): Pick<EmbedImageSpec, "crop" | "brightness" | "contrast" | "transparency">;
 /**
  * Whether an `<xdr:sp>` should import as a drawing shape (`EmbedShapeSpec`)
  * rather than a textbox. Text boxes are excluded explicitly (`txBox="1"`), and
@@ -36,4 +62,5 @@ export declare function parseShapeSpec(shape: any): EmbedShapeSpec;
  * @returns Boolean indicating if the image is inside a cell
  */
 export declare function determineIfOneCellInsideCell(fromColOff: number, fromRowOff: number, fLocksWithSheet: string, cx: number, cy: number): boolean;
+export {};
 //# sourceMappingURL=drawing.d.ts.map

package/dist/esm/excel-parser/plugins/xlsx/drawing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drawing.d.ts","sourceRoot":"","sources":["../../../../../excel-parser/plugins/xlsx/drawing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EAEd,cAAc,EAWf,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAoDrE,MAAM,MAAM,0BAA0B,GAAG,cAAc,GAAG;IACxD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,GAAG,EACZ,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,kBAAkB,EAC7B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,0BAA0B,EAAE,CAAC,CA6dvC;AA6OD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CASlD;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,cAAc,CA8CzD;AA8MD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,OAAO,CAqBT"}
+{"version":3,"file":"drawing.d.ts","sourceRoot":"","sources":["../../../../../excel-parser/plugins/xlsx/drawing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EAEd,cAAc,EACd,cAAc,EAYf,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAoDrE,MAAM,MAAM,0BAA0B,GAAG,cAAc,GAAG;IACxD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,4EAA4E;AAC5E,QAAA,MAAM,sBAAsB;;;;CAIlB,CAAC;AAEX,KAAK,iBAAiB,GAAG,MAAM,OAAO,sBAAsB,CAAC;AAK7D;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,GAAG,EACZ,UAAU,EAAE,MAAM,GACjB,KAAK,CAAC;IACP,IAAI,EAAE,CAAC,OAAO,sBAAsB,CAAC,CAAC,iBAAiB,CAAC,CAAC;IACzD,IAAI,EAAE,GAAG,CAAC;CACX,CAAC,CAkCD;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,GAAG,EACZ,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,kBAAkB,EAC7B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,0BAA0B,EAAE,CAAC,CA8dvC;AASD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,GAAG,GACX,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,GAAG,cAAc,CAAC,CAuC3E;AA6OD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CASlD;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,cAAc,CA8CzD;AA8MD;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,OAAO,CAqBT"}

package/dist/esm/excel-parser/plugins/xlsx/drawing.js

@@ -41,6 +41,54 @@ const CELL_IMAGE_OFFSET_THRESHOLD_PX = 1;
 function emuToPixels(emuValue) {
     return Math.round(emuValue / EMU_PER_PIXEL);
 }
+/** `processAnchors` anchor-type tags, keyed by the drawing element name. */
+const ANCHOR_KIND_BY_ELEMENT = {
+    oneCellAnchor: "oneCellAnchor",
+    twoCellAnchor: "twoCellAnchors",
+    absoluteAnchor: "absoluteAnchors",
+};
+const ANCHOR_ELEMENT_REGEX = /<(?:[A-Za-z_][\w.-]*:)?(oneCellAnchor|twoCellAnchor|absoluteAnchor)(?=[\s/>])/g;
+/**
+ * The `<xdr:wsDr>` anchors in document order — Excel's z-order (first is
+ * the back-most object). The unordered parse keeps document order within one
+ * element name but groups the three anchor kinds apart, so the kind sequence
+ * is read off the raw part and the parsed nodes are dealt out in that order.
+ * Anchors the scan does not account for (namespace quirks) trail in their
+ * parsed order, so nothing is ever dropped.
+ */
+export function anchorsInDocumentOrder(drawing, drawingXml) {
+    const nodesByElement = {
+        oneCellAnchor: [],
+        twoCellAnchor: [],
+        absoluteAnchor: [],
+    };
+    for (const element of Object.keys(nodesByElement)) {
+        const parsed = get(drawing, `xdr:wsDr.xdr:${element}`) || get(drawing, `wsDr.${element}`);
+        if (!parsed)
+            continue;
+        nodesByElement[element] = Array.isArray(parsed) ? parsed : [parsed];
+    }
+    const cursor = {
+        oneCellAnchor: 0,
+        twoCellAnchor: 0,
+        absoluteAnchor: 0,
+    };
+    const ordered = [];
+    for (const match of drawingXml.matchAll(ANCHOR_ELEMENT_REGEX)) {
+        const element = match[1];
+        const node = nodesByElement[element][cursor[element]];
+        if (node === undefined)
+            continue;
+        cursor[element] += 1;
+        ordered.push({ kind: ANCHOR_KIND_BY_ELEMENT[element], node });
+    }
+    for (const element of Object.keys(nodesByElement)) {
+        for (const node of nodesByElement[element].slice(cursor[element])) {
+            ordered.push({ kind: ANCHOR_KIND_BY_ELEMENT[element], node });
+        }
+    }
+    return ordered;
+}
 /**
  * Process different types of image anchors
  * @param anchors The anchor elements from the drawing
@@ -410,6 +458,7 @@ export async function processAnchors(anchors, anchorType, drawingPath, sheetId,
                 imageUrl: createDataUrl(imageData, imageType),
                 type: "image",
                 description: imageName,
+                ...parsePictureAdjustments(picture),
             },
             position,
             draggable: true,
@@ -418,6 +467,56 @@ export async function processAnchors(anchors, anchorType, drawingPath, sheetId,
     }
     return images;
 }
+/** DrawingML per-mille-percent (100000 = 100%) → fraction, or undefined. */
+const pctToFraction = (value) => {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n / 100000 : undefined;
+};
+/**
+ * Picture-format adjustments off an `<xdr:pic>`: `<a:blipFill><a:srcRect>`
+ * (crop), `<a:blip><a:lum bright contrast>` (brightness / contrast) and
+ * `<a:blip><a:alphaModFix amt>` (opacity → `transparency`). Only present
+ * values are returned so an untouched picture stays a bare image spec.
+ */
+export function parsePictureAdjustments(picture) {
+    const blipFill = get(picture, "xdr:blipFill") ?? get(picture, "blipFill") ?? undefined;
+    const blip = get(blipFill, "a:blip") ?? get(blipFill, "blip");
+    const out = {};
+    const srcRect = get(blipFill, "a:srcRect.a$") ?? get(blipFill, "srcRect.a$");
+    if (srcRect) {
+        const crop = {};
+        const left = pctToFraction(srcRect.l);
+        const top = pctToFraction(srcRect.t);
+        const right = pctToFraction(srcRect.r);
+        const bottom = pctToFraction(srcRect.b);
+        if (left)
+            crop.left = left;
+        if (top)
+            crop.top = top;
+        if (right)
+            crop.right = right;
+        if (bottom)
+            crop.bottom = bottom;
+        if (Object.keys(crop).length)
+            out.crop = crop;
+    }
+    const lum = get(blip, "a:lum.a$") ?? get(blip, "lum.a$");
+    if (lum) {
+        const brightness = pctToFraction(lum.bright);
+        const contrast = pctToFraction(lum.contrast);
+        if (brightness)
+            out.brightness = brightness;
+        if (contrast)
+            out.contrast = contrast;
+    }
+    const alpha = pctToFraction(get(blip, "a:alphaModFix.a$.amt") ?? get(blip, "alphaModFix.a$.amt"));
+    if (alpha !== undefined && alpha < 1) {
+        out.transparency = Math.round((1 - alpha) * 100000) / 100000;
+    }
+    return out;
+}
 /**
  * Parse color from DrawingML color element
  * Supports both RGB (srgbClr) and theme colors (schemeClr)

package/dist/esm/excel-parser/plugins/xlsx/form-controls.d.ts

@@ -0,0 +1,70 @@
+import type { EmbeddedObject } from "@rowsncolumns/spreadsheet";
+export declare const CTRL_PROP_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp";
+export declare const VML_DRAWING_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing";
+type CellAnchor = {
+    col: number;
+    colOff: number;
+    row: number;
+    rowOff: number;
+};
+/**
+ * `<controlPr><anchor><from>…</from><to>…</to></anchor>` → the engine's
+ * pixel overlay position (1-based anchor cell, EMU offsets → px, size from
+ * the cell span at the grid defaults — the same approximation the drawing
+ * importer uses for `twoCellAnchor`s).
+ */
+export declare const controlAnchorToOverlayPosition: (from: CellAnchor, to: CellAnchor | undefined) => {
+    anchorCell: {
+        rowIndex: number;
+        columnIndex: number;
+    };
+    offsetXPixels?: number;
+    offsetYPixels?: number;
+    widthPixels?: number;
+    heightPixels?: number;
+};
+/**
+ * Parse an `xl/ctrlProps/ctrlPropN.xml` part: `objectType`, every other
+ * `formControlPr` attribute verbatim, and the literal `itemLst` items.
+ */
+export declare const parseFormControlPr: (ctrlPropDom: any) => {
+    objectType: string;
+    properties: Record<string, string>;
+    listItems?: string[];
+} | undefined;
+/**
+ * Captions live only in the legacy VML part: `<v:shape id="_x0000_s1025">
+ * … <v:textbox><div>Check Box 1</div></v:textbox>`. Returns shapeId → text.
+ * VML is scanned textually — Excel's VML is not reliably well-formed XML.
+ */
+export declare const parseVmlControlCaptions: (vml: string | undefined) => Map<number, string>;
+export type RawWorksheetControl = {
+    shapeId?: number;
+    name?: string;
+    relId?: string;
+    controlProperties: Record<string, string>;
+    moveWithCells?: boolean;
+    sizeWithCells?: boolean;
+    from?: CellAnchor;
+    to?: CellAnchor;
+};
+/**
+ * `<controls>` from a worksheet DOM, whether wrapped in
+ * `<mc:AlternateContent><mc:Choice Requires="x14">` (Excel) or bare.
+ */
+export declare const readWorksheetControls: (sheetDom: any) => RawWorksheetControl[];
+/**
+ * Assemble the sheet's form controls. `loadCtrlProp` resolves a control's
+ * `r:id` to its parsed `ctrlProp` DOM (undefined when the part is missing —
+ * the control is then skipped, Excel would repair it the same way).
+ */
+export declare const buildFormControlEmbeds: ({ controls, sheetId, ctrlProps, captions, }: {
+    controls: RawWorksheetControl[];
+    sheetId: number;
+    ctrlProps: Map<string, ReturnType<typeof parseFormControlPr>>;
+    captions: Map<number, string>;
+}) => EmbeddedObject[];
+/** The `r:id` of a worksheet's `<legacyDrawing>` (VML part), if any. */
+export declare const readLegacyDrawingRelId: (sheetDom: any) => string | undefined;
+export {};
+//# sourceMappingURL=form-controls.d.ts.map

package/dist/esm/excel-parser/plugins/xlsx/form-controls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-controls.d.ts","sourceRoot":"","sources":["../../../../../excel-parser/plugins/xlsx/form-controls.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,cAAc,EACf,MAAM,2BAA2B,CAAC;AAgBnC,eAAO,MAAM,kBAAkB,iFACiD,CAAC;AACjF,eAAO,MAAM,oBAAoB,mFACiD,CAAC;AA6CnF,KAAK,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAe/E;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GACzC,MAAM,UAAU,EAChB,IAAI,UAAU,GAAG,SAAS;gBAKZ;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;oBACrC,MAAM;oBACN,MAAM;kBACR,MAAM;mBACL,MAAM;CAiBxB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAC7B,aAAa,GAAG,KACf;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,GAAG,SAkBH,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,KAAK,MAAM,GAAG,SAAS,KACtB,GAAG,CAAC,MAAM,EAAE,MAAM,CAwBpB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,UAAU,GAAG,KAAG,mBAAmB,EA+BxE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,6CAKpC;IACD,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC;IAC9D,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B,KAAG,cAAc,EA+BjB,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,sBAAsB,GAAI,UAAU,GAAG,KAAG,MAAM,GAAG,SAK/D,CAAC"}