@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/esm/modules/excel/chart/chart-ex-types.js

@@ -0,0 +1,11 @@
+/**
+ * ChartEx (Office 2016+ extended charts) type definitions.
+ *
+ * These types mirror the ECMA-376 Part 1, §21.3 `cx:` namespace for the eight
+ * modern chart types: sunburst, treemap, waterfall, funnel, histogram
+ * (and Pareto), box-whisker, and region map.
+ *
+ * Classic charts live in `c:` (ChartML); chartEx uses its own `cx:` schema
+ * with shared formatting primitives (spPr/txPr) but very different data model.
+ */
+export {};

package/dist/esm/modules/excel/chart/chart-images.js

@@ -0,0 +1,363 @@
+/**
+ * Picture-fill (`<a:blipFill>`) registration for chart parts.
+ *
+ * Callers supply an image payload via `AddChartSeriesOptions.pictureFill.image`;
+ * the builder stores it on the chart model's `spPr.fill.blip._pendingImage`
+ * field. This module consumes those staged payloads at chart-registration
+ * time, pushes the image into the workbook media collection, allocates a
+ * fresh chart-part relationship, and rewrites the blip with the resolved
+ * `r:embed` id.
+ *
+ * The worksheet path calls {@link resolvePendingChartImages} right after
+ * `fillChartCaches` and before the chart entry is stored — at that point
+ * we have both the built model and the owning workbook, so we can do the
+ * binding without requiring callers to juggle rel ids manually.
+ */
+/**
+ * Rel information that {@link resolvePendingChartImages} appends to the
+ * chart entry so the writer can emit the `chart{N}.xml.rels` file and
+ * the correct `r:embed` value inside the chart XML.
+ *
+ * The concrete shape matches the rel entry format used elsewhere
+ * (xlsx-writer relationships XForm) — Id + Type + Target triple. We
+ * hardcode the Type URI in the literal emitted at the call site so
+ * callers don't need to import the workbook-level `RelType` enum.
+ */
+/**
+ * Walk a chart model, resolve every `_pendingImage` blip into a real
+ * workbook media entry + chart relationship, and mutate the model so
+ * the blip references the allocated `rIdN`.
+ *
+ * Safe to call multiple times on the same entry: once a blip has a
+ * `relationshipId` and no `_pendingImage`, it is skipped.
+ *
+ * @param entry   The chart entry being registered. Its `rels` array is
+ *                populated (created if absent) with any freshly
+ *                allocated image relationships.
+ * @param workbook Host workbook exposing `addImage`. Also consulted for
+ *                its internal `_chartRels[n]` bag — those rels are
+ *                loaded from disk during round-trip and carry canonical
+ *                rIds that must NOT collide with freshly allocated
+ *                image rels (the xlsx writer merges both lists and
+ *                silently drops any duplicate Id, which would otherwise
+ *                orphan the image relationship).
+ * @param chartNumber 1-based chart index. Used to look up
+ *                `workbook._chartRels[chartNumber]` so pre-existing
+ *                rels seed the collision set.
+ */
+export function resolvePendingChartImages(entry, workbook, chartNumber) {
+    const blips = collectBlipFills(entry.model);
+    if (blips.length === 0) {
+        return;
+    }
+    const rels = (entry.rels ?? (entry.rels = []));
+    // Scan pre-existing rels so freshly allocated ids don't collide with
+    // rels the user may already have set (e.g. from a partial migration).
+    const usedIds = new Set();
+    for (const rel of rels) {
+        if (rel?.Id) {
+            usedIds.add(rel.Id);
+        }
+    }
+    // Also seed from the workbook-level `_chartRels` bag. Those entries
+    // come from the xlsx reader (round-tripped rels: style / colors /
+    // userShapes / existing images) and are merged BEFORE `entry.rels`
+    // by the writer — the writer drops any `entry.rels` entry whose Id
+    // collides. Without seeding here, a fresh image rel allocated as
+    // `rId1` would be silently dropped by the writer on a round-tripped
+    // chart whose original style sidecar already took `rId1`, leaving
+    // the chart's `r:embed="rId1"` pointing at the wrong target.
+    const chartRelsBag = workbook._chartRels;
+    const existingChartRels = chartRelsBag?.[chartNumber];
+    if (Array.isArray(existingChartRels)) {
+        for (const rel of existingChartRels) {
+            if (rel?.Id) {
+                usedIds.add(rel.Id);
+            }
+        }
+    }
+    let counter = 1;
+    const allocRelId = () => {
+        let id = `rId${counter++}`;
+        while (usedIds.has(id)) {
+            id = `rId${counter++}`;
+        }
+        usedIds.add(id);
+        return id;
+    };
+    for (const blip of blips) {
+        if (blip.relationshipId || blip._pendingImage === undefined) {
+            delete blip._pendingImage;
+            continue;
+        }
+        const normalised = normaliseImage(blip._pendingImage, workbook);
+        if (!normalised) {
+            // Bad payload — drop the blip so we don't emit a broken rel. The
+            // series keeps its `pictureOptions` so the chart still opens.
+            delete blip._pendingImage;
+            continue;
+        }
+        const { mediaId, extension } = normalised;
+        const relId = allocRelId();
+        blip.relationshipId = relId;
+        delete blip._pendingImage;
+        rels.push({
+            Id: relId,
+            Type: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image",
+            // Chart parts live at `xl/charts/chart{N}.xml`; images live at
+            // `xl/media/image{M}.{ext}`. The relative Target is therefore
+            // `../media/image{M}.{ext}`. Media ids are 0-based in the workbook
+            // collection but the on-disk naming is 1-based, hence `mediaId + 1`.
+            Target: `../media/image${mediaId + 1}.${extension}`
+        });
+    }
+}
+/**
+ * Traverse every `spPr` slot in a chart model and return the list of
+ * {@link ChartBlipFill} objects that carry picture fills.
+ *
+ * The traversal is intentionally narrow: we only visit the locations
+ * where `a:blipFill` is actually legal (series, data points, chart
+ * frame, plot area, walls, axis, legend, gridlines, drop/hi-low lines,
+ * trendline labels…). It walks both the primary (`chart.plotArea`) and
+ * pivot-format (`chart.pivotFormats`) branches.
+ */
+function collectBlipFills(model) {
+    const out = [];
+    const visitSpPr = (spPr) => {
+        const blip = spPr?.fill?.blip;
+        if (blip && (blip.relationshipId || blip._pendingImage)) {
+            out.push(blip);
+        }
+    };
+    visitSpPr(model.spPr);
+    visitSpPr(model.chart?.title?.spPr);
+    visitSpPr(model.chart?.floor);
+    visitSpPr(model.chart?.sideWall);
+    visitSpPr(model.chart?.backWall);
+    visitSpPr(model.chart?.plotArea?.spPr);
+    for (const group of model.chart?.plotArea?.chartTypes ?? []) {
+        visitGroup(group, visitSpPr);
+    }
+    for (const axis of model.chart?.plotArea?.axes ?? []) {
+        visitSpPr(axis.spPr);
+        visitSpPr(axis.title?.spPr);
+        // `majorGridlines` and `minorGridlines` are themselves `ShapeProperties`
+        // (the grid-line style uses the same DrawingML fill/line/effect
+        // vocabulary as any other shape); pass them through directly rather
+        // than treating them as containers.
+        visitSpPr(axis.majorGridlines);
+        visitSpPr(axis.minorGridlines);
+    }
+    visitSpPr(model.chart?.legend?.spPr);
+    for (const pf of model.chart?.pivotFormats ?? []) {
+        visitSpPr(pf.spPr);
+    }
+    return out;
+}
+function visitGroup(group, visit) {
+    const groupWithSeries = group;
+    if (groupWithSeries.series) {
+        for (const s of groupWithSeries.series) {
+            visit(s.spPr);
+            // Series-level data labels and trendlines are DrawingML shapes too;
+            // both can carry picture fills (e.g. a branded label background).
+            const dataLabels = s.dataLabels;
+            visit(dataLabels?.spPr);
+            const trendlines = s.trendlines;
+            if (trendlines) {
+                for (const tl of trendlines) {
+                    visit(tl.spPr);
+                }
+            }
+            // Per-point overrides live on specific series subtypes (BarSeries,
+            // LineSeries, …) as `dataPoints?: DataPoint[]`. They all share the
+            // same shape — walk them generically without narrowing to each
+            // discriminated union variant.
+            const dps = s.dataPoints;
+            if (dps) {
+                for (const dp of dps) {
+                    visit(dp.spPr);
+                }
+            }
+        }
+    }
+    visit(groupWithSeries.dropLines);
+    visit(groupWithSeries.hiLowLines);
+    visit(groupWithSeries.serLines);
+    visit(groupWithSeries.upDownBars?.upBars);
+    visit(groupWithSeries.upDownBars?.downBars);
+}
+/**
+ * Coerce a user-facing {@link AddChartPictureFillImage} into a workbook
+ * media entry. Returns `{mediaId, extension}` or `undefined` when the
+ * payload is unusable (empty / unknown format).
+ *
+ * Side-effect: when the caller passes raw data (not `workbookImageId`),
+ * a new media entry is created on the workbook.
+ */
+function normaliseImage(image, workbook) {
+    // Re-use an already-registered workbook image.
+    if (typeof image === "object" && !Array.isArray(image) && "workbookImageId" in image) {
+        const existing = workbook.getImage(image.workbookImageId);
+        if (!existing) {
+            return undefined;
+        }
+        // DrawingML's `<a:blipFill>` technically accepts more formats (BMP,
+        // TIFF, EMF/WMF) but the workbook media pipeline and our
+        // magic-byte sniffer only cover PNG / JPEG / GIF. Silently
+        // dropping the blip is preferable to emitting a rel entry whose
+        // media bytes would be mislabelled and fail to decode in Excel.
+        // Callers needing the exotic formats should add them to the
+        // workbook media collection separately and use `workbookImageId`.
+        const raw = existing.extension;
+        if (raw !== "png" && raw !== "jpeg" && raw !== "gif") {
+            return undefined;
+        }
+        return { mediaId: image.workbookImageId, extension: raw };
+    }
+    // Raw binary payload. `instanceof Uint8Array` is realm-sensitive:
+    // a buffer produced inside a Web Worker or another iframe has a
+    // different `Uint8Array` prototype, so the operator returns false
+    // even though the object is a genuine byte array. Duck-typing via
+    // `ArrayBuffer.isView` + `BYTES_PER_ELEMENT === 1` covers both the
+    // same-realm path and cross-realm buffers (workers, SharedWorkers,
+    // MessagePort transfers, `structuredClone` round-trips), and still
+    // excludes `Uint16Array` / `DataView` etc. — `DataView` has
+    // no `BYTES_PER_ELEMENT` on instances (the property is on the
+    // constructor), so the check rejects it naturally. `Int8Array` /
+    // `Uint8ClampedArray` DO pass the check; that's intentional —
+    // both carry byte-granular binary data and the sniffer below
+    // operates on the first few bytes regardless of typed-array
+    // signedness. The workbook image store only needs a
+    // `Uint8Array`, so we coerce through a shared underlying buffer.
+    if (ArrayBuffer.isView(image) &&
+        image.BYTES_PER_ELEMENT === 1) {
+        const view = image;
+        const bytes = view instanceof Uint8Array
+            ? view
+            : new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+        const ext = sniffImageExtension(bytes);
+        if (!ext) {
+            // Unknown format (WebP / AVIF / TIFF / …) — drop the blip rather
+            // than mislabel it as `png`. The caller keeps `pictureOptions`
+            // so the rest of the chart still renders.
+            return undefined;
+        }
+        const id = workbook.addImage({ extension: ext, buffer: bytes });
+        return { mediaId: id, extension: ext };
+    }
+    // String — either a data URL or a bare base64 string.
+    if (typeof image === "string") {
+        const parsed = parseDataUrlOrBase64(image);
+        if (!parsed) {
+            return undefined;
+        }
+        const id = workbook.addImage({ extension: parsed.extension, base64: parsed.base64 });
+        return { mediaId: id, extension: parsed.extension };
+    }
+    // Structured ChartPictureFillImageData.
+    const data = image;
+    if (data.buffer != null) {
+        // Use ArrayBuffer.isView to handle cross-realm Uint8Array instances
+        // that fail `instanceof` checks but are structurally identical.
+        const raw = data.buffer;
+        if (ArrayBuffer.isView(raw)) {
+            const view = raw;
+            const bytes = view instanceof Uint8Array
+                ? view
+                : new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+            const id = workbook.addImage({ extension: data.extension, buffer: bytes });
+            return { mediaId: id, extension: data.extension };
+        }
+    }
+    if (typeof data.base64 === "string" && data.base64.length > 0) {
+        const id = workbook.addImage({ extension: data.extension, base64: data.base64 });
+        return { mediaId: id, extension: data.extension };
+    }
+    return undefined;
+}
+/**
+ * Parse a `data:image/<type>;base64,…` URL or a bare base64 string into
+ * `{ extension, base64 }`. Returns `undefined` for empty or
+ * unrecognised input (including data URLs whose content-type is not one
+ * of the three `<a:blipFill>`-supported formats — e.g. `image/svg+xml`
+ * or `image/bmp`). Callers interpret `undefined` as "drop the blip"
+ * rather than emitting a corrupted `.png` file.
+ */
+function parseDataUrlOrBase64(input) {
+    if (!input) {
+        return undefined;
+    }
+    // `data:image/<subtype>[;param=value]*;base64,<payload>`. Support
+    // multiple parameter segments (e.g. `;charset=utf-8;base64,...`).
+    // The previous `(?:;[^,]*)?` admitted only a single parameter AND
+    // used a greedy class that could swallow the required `;base64`
+    // token, forcing backtracking that silently failed for common
+    // multi-param forms. Allow any number of `;token[=value]` groups
+    // before the required trailing `;base64,`.
+    const dataUrl = /^data:image\/([a-z+]+)(?:;[^,;=]+(?:=[^,;]*)?)*;base64,(.+)$/i.exec(input.trim());
+    if (dataUrl) {
+        const rawType = dataUrl[1].toLowerCase();
+        const ext = rawType === "jpg"
+            ? "jpeg"
+            : rawType === "png" || rawType === "jpeg" || rawType === "gif"
+                ? rawType
+                : undefined;
+        if (ext === undefined) {
+            // Content-type outside the `<a:blipFill>` white-list (e.g.
+            // `svg+xml`, `bmp`, `webp`, `tiff`). Dropping is better than
+            // silently relabelling an SVG payload as `image/png` — Excel
+            // would try to decode SVG bytes with the PNG parser and either
+            // error out or leave an invisible shape.
+            return undefined;
+        }
+        return { extension: ext, base64: dataUrl[2] };
+    }
+    // Bare base64 — extension unknown, default to PNG (the most common
+    // Excel bar-fill choice). Callers who need precision should pass a
+    // structured ChartPictureFillImageData.
+    return { extension: "png", base64: input };
+}
+/**
+ * Identify the image format from the first few magic bytes.
+ *
+ * Supports the three extensions Excel accepts in `<a:blipFill>` — PNG,
+ * JPEG, GIF. Anything else falls back to PNG (which is the safest
+ * default: Excel will try to decode and most viewers treat unrecognised
+ * binary as PNG).
+ */
+/**
+ * Inspect the first few bytes of `data` and return the matching
+ * `<a:blipFill>`-supported image extension, or `undefined` when the
+ * payload doesn't look like one of the three supported formats
+ * (PNG / JPEG / GIF). Callers treat `undefined` as "drop the blip" —
+ * preferable to emitting a `.png` file whose decoded bytes are
+ * actually WebP / AVIF / TIFF, which Excel would fail to render.
+ */
+function sniffImageExtension(data) {
+    if (data.length >= 8 &&
+        data[0] === 0x89 &&
+        data[1] === 0x50 &&
+        data[2] === 0x4e &&
+        data[3] === 0x47 &&
+        data[4] === 0x0d &&
+        data[5] === 0x0a &&
+        data[6] === 0x1a &&
+        data[7] === 0x0a) {
+        return "png";
+    }
+    if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+        return "jpeg";
+    }
+    if (data.length >= 6 &&
+        data[0] === 0x47 &&
+        data[1] === 0x49 &&
+        data[2] === 0x46 &&
+        data[3] === 0x38 &&
+        (data[4] === 0x37 || data[4] === 0x39) &&
+        data[5] === 0x61) {
+        return "gif";
+    }
+    return undefined;
+}

package/dist/esm/modules/excel/chart/chart-presets.js

@@ -0,0 +1,179 @@
+import { ChartOptionsError } from "../errors.js";
+// Shared factory for bar/column preset variants. Accepts a base type ("bar"
+// or "bar3D"), direction, grouping and an optional 3-D shape. When `shape`
+// is passed the type is always forced to "bar3D" (cone/cylinder/pyramid
+// require 3D). The previous code had two nearly-identical factories
+// (`barPreset` / `bar3DPreset`) that differed only in the default type.
+const barPreset = (barDir, grouping, shape, type = "bar") => ({
+    options: shape ? { type: "bar3D", barDir, grouping, shape } : { type, barDir, grouping }
+});
+const bar3DPreset = (barDir, grouping, shape) => barPreset(barDir, grouping, shape, "bar3D");
+export const CHART_PRESETS = {
+    columnClustered: barPreset("col", "clustered"),
+    columnStacked: barPreset("col", "stacked"),
+    columnStacked100: barPreset("col", "percentStacked"),
+    columnPercentStacked: barPreset("col", "percentStacked"),
+    colClustered: barPreset("col", "clustered"),
+    colStacked: barPreset("col", "stacked"),
+    colPercentStacked: barPreset("col", "percentStacked"),
+    colStacked100: barPreset("col", "percentStacked"),
+    barClustered: barPreset("bar", "clustered"),
+    barStacked: barPreset("bar", "stacked"),
+    barPercentStacked: barPreset("bar", "percentStacked"),
+    barStacked100: barPreset("bar", "percentStacked"),
+    pieOfPie: { options: { type: "ofPie", ofPieType: "pie" } },
+    barOfPie: { options: { type: "ofPie", ofPieType: "bar" } },
+    column3DClustered: bar3DPreset("col", "clustered"),
+    column3DStacked: bar3DPreset("col", "stacked"),
+    column3DStacked100: bar3DPreset("col", "percentStacked"),
+    col3DClustered: bar3DPreset("col", "clustered"),
+    col3DStacked: bar3DPreset("col", "stacked"),
+    col3DStacked100: bar3DPreset("col", "percentStacked"),
+    bar3DClustered: bar3DPreset("bar", "clustered"),
+    bar3DStacked: bar3DPreset("bar", "stacked"),
+    bar3DStacked100: bar3DPreset("bar", "percentStacked"),
+    col3DConeClustered: bar3DPreset("col", "clustered", "cone"),
+    col3DConeStacked: bar3DPreset("col", "stacked", "cone"),
+    col3DConeStacked100: bar3DPreset("col", "percentStacked", "cone"),
+    coneColClustered: bar3DPreset("col", "clustered", "cone"),
+    coneColStacked: bar3DPreset("col", "stacked", "cone"),
+    coneColStacked100: bar3DPreset("col", "percentStacked", "cone"),
+    bar3DConeClustered: bar3DPreset("bar", "clustered", "cone"),
+    bar3DConeStacked: bar3DPreset("bar", "stacked", "cone"),
+    bar3DConeStacked100: bar3DPreset("bar", "percentStacked", "cone"),
+    coneBarClustered: bar3DPreset("bar", "clustered", "cone"),
+    coneBarStacked: bar3DPreset("bar", "stacked", "cone"),
+    coneBarStacked100: bar3DPreset("bar", "percentStacked", "cone"),
+    col3DCylinderClustered: bar3DPreset("col", "clustered", "cylinder"),
+    col3DCylinderStacked: bar3DPreset("col", "stacked", "cylinder"),
+    col3DCylinderStacked100: bar3DPreset("col", "percentStacked", "cylinder"),
+    cylinderColClustered: bar3DPreset("col", "clustered", "cylinder"),
+    cylinderColStacked: bar3DPreset("col", "stacked", "cylinder"),
+    cylinderColStacked100: bar3DPreset("col", "percentStacked", "cylinder"),
+    bar3DCylinderClustered: bar3DPreset("bar", "clustered", "cylinder"),
+    bar3DCylinderStacked: bar3DPreset("bar", "stacked", "cylinder"),
+    bar3DCylinderStacked100: bar3DPreset("bar", "percentStacked", "cylinder"),
+    cylinderBarClustered: bar3DPreset("bar", "clustered", "cylinder"),
+    cylinderBarStacked: bar3DPreset("bar", "stacked", "cylinder"),
+    cylinderBarStacked100: bar3DPreset("bar", "percentStacked", "cylinder"),
+    col3DPyramidClustered: bar3DPreset("col", "clustered", "pyramid"),
+    col3DPyramidStacked: bar3DPreset("col", "stacked", "pyramid"),
+    col3DPyramidStacked100: bar3DPreset("col", "percentStacked", "pyramid"),
+    pyramidColClustered: bar3DPreset("col", "clustered", "pyramid"),
+    pyramidColStacked: bar3DPreset("col", "stacked", "pyramid"),
+    pyramidColStacked100: bar3DPreset("col", "percentStacked", "pyramid"),
+    bar3DPyramidClustered: bar3DPreset("bar", "clustered", "pyramid"),
+    bar3DPyramidStacked: bar3DPreset("bar", "stacked", "pyramid"),
+    bar3DPyramidStacked100: bar3DPreset("bar", "percentStacked", "pyramid"),
+    pyramidBarClustered: bar3DPreset("bar", "clustered", "pyramid"),
+    pyramidBarStacked: bar3DPreset("bar", "stacked", "pyramid"),
+    pyramidBarStacked100: bar3DPreset("bar", "percentStacked", "pyramid"),
+    line: { options: { type: "line" } },
+    lineMarkers: { options: { type: "line", showMarker: true } },
+    lineStacked: { options: { type: "line", grouping: "stacked" } },
+    lineStacked100: { options: { type: "line", grouping: "percentStacked" } },
+    pie: { options: { type: "pie" } },
+    pieExploded: { options: { type: "pie" }, seriesDefaults: { explosion: 25 } },
+    pie3D: { options: { type: "pie3D" } },
+    pieExploded3D: { options: { type: "pie3D" }, seriesDefaults: { explosion: 25 } },
+    doughnut: { options: { type: "doughnut" } },
+    doughnutExploded: {
+        options: { type: "doughnut", holeSize: 50 },
+        seriesDefaults: { explosion: 25 }
+    },
+    area: { options: { type: "area" } },
+    areaStacked: { options: { type: "area", grouping: "stacked" } },
+    areaStacked100: { options: { type: "area", grouping: "percentStacked" } },
+    area3D: { options: { type: "area3D" } },
+    area3DStacked: { options: { type: "area3D", grouping: "stacked" } },
+    area3DStacked100: { options: { type: "area3D", grouping: "percentStacked" } },
+    scatter: { options: { type: "scatter", scatterStyle: "marker" } },
+    scatterMarker: { options: { type: "scatter", scatterStyle: "marker" } },
+    scatterStraight: { options: { type: "scatter", scatterStyle: "lineMarker" } },
+    scatterLines: { options: { type: "scatter", scatterStyle: "lineMarker" } },
+    scatterLinesNoMarkers: { options: { type: "scatter", scatterStyle: "line" } },
+    scatterSmooth: { options: { type: "scatter", scatterStyle: "smoothMarker" } },
+    scatterSmoothMarker: { options: { type: "scatter", scatterStyle: "smoothMarker" } },
+    scatterSmoothNoMarkers: { options: { type: "scatter", scatterStyle: "smooth" } },
+    bubble: { options: { type: "bubble" } },
+    bubble3D: { options: { type: "bubble" }, seriesDefaults: { bubble3D: true } },
+    radar: { options: { type: "radar", radarStyle: "standard" } },
+    radarMarkers: { options: { type: "radar", radarStyle: "marker" } },
+    radarFilled: { options: { type: "radar", radarStyle: "filled" } },
+    stockHLC: { options: { type: "stock", hiLowLines: true } },
+    stockOHLC: { options: { type: "stock", upDownBars: true, hiLowLines: true } },
+    // `stockVHLC` / `stockVOHLC` (Volume-HLC / Volume-OHLC) used to be
+    // accepted here, but they require a combo chart (a column chart for
+    // volume layered on top of an HLC / OHLC stock chart) that a
+    // single `AddChartOptions` cannot express. Quietly aliasing them to
+    // the non-volume variants produced a chart that looked wrong
+    // without telling the caller. Build the combo manually via
+    // `buildComboChartModel({ groups: [{ type: "bar", barDir: "col", ... },
+    // { type: "stock", hiLowLines: true, useSecondaryAxis: true, ... }] })`
+    // when you need the volume overlay.
+    surface: { options: { type: "surface" } },
+    surface3D: { options: { type: "surface3D" } },
+    // "Top View" in Excel's surface submenu is just a `surface3D` chart
+    // rotated to look straight down — same chart type, same series
+    // layout, different `view3D` angles. Setting `rotX: 90` spins the
+    // camera down onto the XY plane; `rotY: 0` removes the side tilt
+    // so the grid reads as a flat mosaic instead of an oblique slab.
+    // The resulting chart opens in Excel with the correct camera, and
+    // our own renderer projects it via `resolveBar3DProjection` /
+    // surface cells without any preset-specific branching.
+    surfaceTopView: { options: { type: "surface3D", view3D: { rotX: 90, rotY: 0 } } },
+    // A flat 2-D surface (no `view3D`) IS Excel's "Contour" chart.
+    // Keeping the preset as `surface` matches Excel's own internal
+    // representation — `c:surfaceChart` without `c:view3D` is how
+    // Excel serialises a contour chart authored from the UI.
+    contour: { options: { type: "surface" } },
+    wireframeSurface: { options: { type: "surface3D", wireframe: true } },
+    surface3DWireframe: { options: { type: "surface3D", wireframe: true } },
+    surfaceWireframe: { options: { type: "surface3D", wireframe: true } },
+    wireframeContour: { options: { type: "surface", wireframe: true } },
+    topViewWireframe: {
+        options: { type: "surface3D", wireframe: true, view3D: { rotX: 90, rotY: 0 } }
+    }
+};
+export const EXCEL_CHART_PRESETS = Object.keys(CHART_PRESETS);
+export const CHART_EX_PRESETS = {
+    histogram: { options: { type: "histogram" } },
+    pareto: { options: { type: "pareto" } },
+    waterfall: { options: { type: "waterfall" } },
+    funnel: { options: { type: "funnel" } },
+    treemap: { options: { type: "treemap" } },
+    sunburst: { options: { type: "sunburst" } },
+    boxWhisker: { options: { type: "boxWhisker" } },
+    boxAndWhisker: { options: { type: "boxWhisker" } },
+    regionMap: { options: { type: "regionMap" } },
+    map: { options: { type: "regionMap" } }
+};
+export const EXCEL_CHART_EX_PRESETS = Object.keys(CHART_EX_PRESETS);
+export function applyChartPreset(preset, options) {
+    const config = CHART_PRESETS[preset];
+    if (!config) {
+        throw new ChartOptionsError(`Unknown chart preset: ${preset}.`);
+    }
+    // `type` is required on `PresetConfig.options`, so this assignment is
+    // type-safe without a non-null assertion.
+    const merged = {
+        ...config.options,
+        ...options,
+        type: options.type ?? config.options.type
+    };
+    if (config.seriesDefaults && merged.series) {
+        merged.series = merged.series.map(series => ({ ...config.seriesDefaults, ...series }));
+    }
+    return merged;
+}
+export function applyChartExPreset(preset, options) {
+    const config = CHART_EX_PRESETS[preset];
+    if (!config) {
+        throw new ChartOptionsError(`Unknown chartEx preset: ${preset}.`);
+    }
+    return {
+        ...config.options,
+        ...options,
+        type: options.type ?? config.options.type
+    };
+}