@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/esm/modules/excel/chart/topojson.js

@@ -0,0 +1,236 @@
+/**
+ * Minimal, zero-dependency TopoJSON feature extractor.
+ *
+ * TopoJSON (https://github.com/topojson/topojson-specification) encodes
+ * geometries as indices into a shared arc table, optionally with an
+ * integer quantisation grid that is dequantised via `transform`. Full
+ * support (mesh, merge, presimplify…) belongs to a dedicated library;
+ * this module implements only what the `regionMap` renderer needs:
+ *
+ * 1. Parse a {@link TopologyLike} object produced by any TopoJSON 1.x
+ *    emitter (d3, topojson-server, world-atlas bundles).
+ * 2. Dequantise integer-encoded arcs back to absolute lon/lat pairs.
+ * 3. Resolve a geometry (`Polygon` / `MultiPolygon` / `LineString` /
+ *    `MultiLineString` / `Point` / `MultiPoint`) into drawable rings.
+ *
+ * The shapes here mirror what the TopoJSON 1.x spec emits but keep
+ * the types narrow — unknown fields (`bbox`, vendor extensions) are
+ * ignored, not stripped. Users who need the full spec should use the
+ * upstream `topojson-client` package; doing so does not conflict with
+ * this module because both return `[lon, lat]` coordinate arrays in
+ * the geometry output.
+ */
+import { ChartOptionsError } from "../errors.js";
+/**
+ * Resolve a named object from a {@link TopologyLike} into a flat list
+ * of `{ id, rings }` records. Each `rings[0]` is the outer ring and
+ * the remainder are holes. For `LineString` / `MultiLineString`,
+ * `rings` contains the open polylines; the caller is expected to
+ * treat them as un-closed paths.
+ *
+ * Throws if the object is missing or not a recognised geometry type —
+ * preferring a loud failure over silent "empty map" output, which is
+ * almost always a wiring bug on the caller's side.
+ */
+export function resolveTopologyObject(topology, objectName) {
+    const obj = topology.objects?.[objectName];
+    if (!obj) {
+        throw new ChartOptionsError(`resolveTopologyObject: topology.objects['${objectName}'] not found (available: ${Object.keys(topology.objects ?? {}).join(", ") || "<none>"}).`);
+    }
+    if (!Array.isArray(topology.arcs)) {
+        // Malformed input — TopoJSON spec requires `arcs` to be an array. We
+        // bail out explicitly (rather than throwing inside `decode` below
+        // from a `TypeError: Cannot read properties of undefined`) so the
+        // caller sees a clear message.
+        throw new ChartOptionsError(`resolveTopologyObject: topology.arcs is missing or not an array; cannot decode geometry.`);
+    }
+    const rawScale = topology.transform?.scale;
+    const rawTranslate = topology.transform?.translate;
+    // Defensive: verify both are finite 2-tuples before forwarding to
+    // `dequantiseArc`. A single `NaN` / `Infinity` in scale or translate
+    // would otherwise propagate through every coordinate.
+    const isFinitePair = (v) => Array.isArray(v) && v.length === 2 && Number.isFinite(v[0]) && Number.isFinite(v[1]);
+    const scale = isFinitePair(rawScale) ? rawScale : undefined;
+    const translate = isFinitePair(rawTranslate) ? rawTranslate : undefined;
+    // Cache decoded arcs by their positive index. A world-atlas topology
+    // typically shares each arc between 2–4 neighbouring countries; with
+    // no cache, `dequantiseArc` (an O(n) delta-accumulator) runs that
+    // many times per render. The cache turns the inner loop into O(1)
+    // for repeated references without changing any semantics — decoded
+    // points are read-only from the caller's perspective.
+    const decodedArcs = new Map();
+    const decode = (arcIndex) => {
+        const reverse = arcIndex < 0;
+        // Topojson spec: a negative index means the 1s-complement of the arc's
+        // positive index, used to indicate reverse traversal.
+        const positive = reverse ? ~arcIndex : arcIndex;
+        let points = decodedArcs.get(positive);
+        if (!points) {
+            const rawArc = topology.arcs[positive];
+            if (!rawArc) {
+                return [];
+            }
+            points = dequantiseArc(rawArc, scale, translate);
+            decodedArcs.set(positive, points);
+        }
+        // Always return a fresh array on reverse — callers mutate the
+        // returned array in some code paths (`joinRing` concat), and we
+        // don't want the cached copy to be mutated.
+        return reverse ? points.slice().reverse() : points.slice();
+    };
+    const geometries = obj.type === "GeometryCollection" ? obj.geometries : [obj];
+    const results = [];
+    for (const geom of geometries) {
+        const rings = [];
+        switch (geom.type) {
+            case "Polygon": {
+                for (const ring of geom.arcs) {
+                    rings.push(joinRing(ring, decode));
+                }
+                break;
+            }
+            case "MultiPolygon": {
+                for (const poly of geom.arcs) {
+                    for (const ring of poly) {
+                        rings.push(joinRing(ring, decode));
+                    }
+                }
+                break;
+            }
+            case "LineString": {
+                rings.push(joinRing(geom.arcs, decode));
+                break;
+            }
+            case "MultiLineString": {
+                for (const line of geom.arcs) {
+                    rings.push(joinRing(line, decode));
+                }
+                break;
+            }
+            case "Point": {
+                // Point / MultiPoint coordinates live in the same quantised
+                // grid as arc coordinates when the topology carries a
+                // `transform`. Previously the coordinates were pushed raw,
+                // so Point features from a d3 / topojson-server-quantised
+                // topology plotted at integer pixel positions (e.g.
+                // `[5243, 3012]`) instead of their lon/lat values. Dequantise
+                // through the same pipeline arcs use to keep the output space
+                // consistent. Point coordinates are NOT delta-encoded — each
+                // is absolute — so wrap the single pair in a synthetic "arc"
+                // and only apply the scale/translate step.
+                if (scale && translate) {
+                    const [x, y] = geom.coordinates;
+                    if (Number.isFinite(x) && Number.isFinite(y)) {
+                        rings.push([[x * scale[0] + translate[0], y * scale[1] + translate[1]]]);
+                    }
+                }
+                else {
+                    rings.push([geom.coordinates]);
+                }
+                break;
+            }
+            case "MultiPoint": {
+                if (scale && translate) {
+                    const ring = [];
+                    for (const [x, y] of geom.coordinates) {
+                        if (Number.isFinite(x) && Number.isFinite(y)) {
+                            ring.push([x * scale[0] + translate[0], y * scale[1] + translate[1]]);
+                        }
+                    }
+                    if (ring.length > 0) {
+                        rings.push(ring);
+                    }
+                }
+                else {
+                    for (const pt of geom.coordinates) {
+                        rings.push([pt]);
+                    }
+                }
+                break;
+            }
+            default: {
+                // Unknown geometry type — skip instead of throwing so a
+                // collection containing a few unsupported entries still
+                // renders the rest. The caller can detect empty output and
+                // decide whether to warn.
+                break;
+            }
+        }
+        results.push({
+            id: geom.id,
+            properties: "properties" in geom && geom.properties
+                ? geom.properties
+                : undefined,
+            geometry: geom,
+            rings
+        });
+    }
+    return results;
+}
+/**
+ * Concatenate a list of arc indices into one ring, removing the
+ * duplicate join points where two arcs share an endpoint. Follows the
+ * TopoJSON spec: when joining arc B to arc A, the first point of B is
+ * identical to the last point of A and must be dropped.
+ */
+function joinRing(arcIndices, decode) {
+    const out = [];
+    for (const arcIndex of arcIndices) {
+        const pts = decode(arcIndex);
+        if (pts.length === 0) {
+            continue;
+        }
+        // "First non-empty arc" is when `out` is still empty — push all
+        // points including the starting one. For every subsequent arc, the
+        // join point (pts[0]) is identical to `out[-1]` by TopoJSON spec
+        // §2.1.4 and must be dropped.
+        //
+        // Using `out.length === 0` instead of `i === 0` matters when the
+        // first arc decoded empty: a naive "i === 0" check would drop the
+        // starting point of the first real (non-empty) arc, shifting the
+        // whole ring by one vertex.
+        if (out.length === 0) {
+            out.push(...pts);
+        }
+        else {
+            for (let j = 1; j < pts.length; j++) {
+                out.push(pts[j]);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Undo delta encoding and apply the quantisation transform. Each
+ * consecutive `[dx, dy]` pair in the source represents an offset
+ * from the previous point; the first pair is absolute.
+ */
+function dequantiseArc(arc, scale, translate) {
+    if (!scale || !translate) {
+        // Arcs already hold floating-point absolute coordinates.
+        //
+        // Filter out non-finite points so a single malformed pair doesn't
+        // propagate `NaN` into downstream `[x, y]` consumers (SVG coord
+        // printing, PDF path construction) where it silently produces
+        // broken geometry.
+        return arc
+            .filter(pair => Array.isArray(pair) && Number.isFinite(pair[0]) && Number.isFinite(pair[1]))
+            .map(([x, y]) => [x, y]);
+    }
+    const out = [];
+    let qx = 0;
+    let qy = 0;
+    for (const pair of arc) {
+        // Defensive check: any non-finite delta would permanently poison
+        // the running accumulator, so we abort the whole arc rather than
+        // emit progressively worse `NaN` vertices.
+        if (!Array.isArray(pair) || !Number.isFinite(pair[0]) || !Number.isFinite(pair[1])) {
+            return [];
+        }
+        const [dx, dy] = pair;
+        qx += dx;
+        qy += dy;
+        out.push([qx * scale[0] + translate[0], qy * scale[1] + translate[1]]);
+    }
+    return out;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Chart type definitions for ExcelTS
+ *
+ * Covers the full OOXML DrawingML Chart specification (c: namespace).
+ * Every chart in an XLSX file is a `c:chartSpace` containing a `c:chart`
+ * which holds a `c:plotArea` with one or more chart type groups.
+ */
+export {};

package/dist/esm/modules/excel/chart-host-registry.js

@@ -0,0 +1,90 @@
+/**
+ * Chart Support Registry
+ *
+ * A tiny indirection layer that lets `Worksheet`, `Workbook` and
+ * `Chartsheet` call into chart-building, chart-rendering and chart
+ * cache-population code **only if the host application has opted in**
+ * by calling `installChartSupport()` from
+ * `@cj-tech-master/excelts/chart`.
+ *
+ * ## Why a registry
+ *
+ * The chart module ships 17 files covering classic charts, ChartEx
+ * (Excel 2016+), SVG/PNG/PDF renderers, preset catalogues, shape
+ * properties, TopoJSON region maps and cache populators — roughly
+ * 30,000 lines of TypeScript. Empirical measurement shows that making
+ * `Worksheet` import from chart directly forces ~1.2 MB of chart code
+ * into every consumer bundle, even for consumers who only read and
+ * write cells.
+ *
+ * This file is the single point of indirection. Importing `Worksheet`
+ * pulls it in (~1 KB) but does NOT pull in the chart implementation;
+ * the implementation only arrives once someone calls
+ * `installChartSupport()`, which bundlers resolve to the
+ * `@cj-tech-master/excelts/chart` subpath import graph.
+ *
+ * If chart-manipulating APIs (`worksheet.addChart()`, `workbook.writeFile()`
+ * with charts, etc.) are called without `installChartSupport()` having
+ * run, a clear error is thrown telling the developer how to fix it.
+ *
+ * ## Why it lives in `excel/` rather than `excel/chart/`
+ *
+ * Host-registry pattern convention: the slot lives with the consumer,
+ * not with the provider. `worksheet.ts`, `workbook.browser.ts` and
+ * `chartsheet.ts` are the consumers and they all live in `excel/`, so
+ * the slot sits next to them. The chart module only depends on it when
+ * `install()` is called — a one-way arrow from provider to consumer.
+ *
+ * This differs from `@formula/host-registry` which lives inside the
+ * formula module because formula is a separate top-level module (layer
+ * 3) that cannot import from excel. Chart is nested under excel
+ * (layer 4), so the slot naturally lives in excel.
+ *
+ * ## Relationship to formula's host-registry
+ *
+ * The two registries are independent slots for independent optional
+ * features. A consumer may install chart without formula, formula
+ * without chart, both, or neither.
+ */
+let installed = null;
+/**
+ * Install a chart runtime implementation. Called from
+ * `installChartSupport()` in the `@cj-tech-master/excelts/chart`
+ * subpath.
+ *
+ * Re-installing is allowed — the last registration wins. Passing
+ * `null` uninstalls chart support, which is useful for tests that
+ * exercise the "no chart" error path.
+ */
+export function registerChartSupport(support) {
+    installed = support;
+}
+/** Returns true when chart support has been installed. */
+export function hasChartSupport() {
+    return installed !== null;
+}
+/**
+ * Retrieve the installed chart support. Throws a descriptive error if
+ * no chart support is installed.
+ */
+export function getChartSupport() {
+    if (!installed) {
+        throw new Error("No chart support is installed. " +
+            "Call `installChartSupport()` from `@cj-tech-master/excelts/chart` " +
+            "once at startup to enable chart creation, loading, and " +
+            "serialisation during `workbook.xlsx.writeFile()`.");
+    }
+    return installed;
+}
+/**
+ * Retrieve installed chart support, or `null` if none is installed.
+ *
+ * Used by code paths that can gracefully degrade when chart support is
+ * missing — e.g. ChartEx loading, which can preserve raw XML verbatim
+ * without a full parse when chart support is absent. Note that classic
+ * chart loading currently requires chart support to be installed (the
+ * reader calls `getChartSupport()` unconditionally for classic charts).
+ */
+export function tryGetChartSupport() {
+    return installed;
+}

package/dist/esm/modules/excel/chartsheet.js

@@ -0,0 +1,196 @@
+import { getChartSupport } from "./chart-host-registry.js";
+/**
+ * Nominal anchor range for the full-sheet chart in a chartsheet.
+ * Chartsheet charts fill the entire sheet viewport; the anchor value is
+ * never used for positioning but is required by the Chart constructor to
+ * initialise its internal two-cell-anchor model.
+ */
+const CHARTSHEET_ANCHOR_RANGE = "A1:K15";
+/**
+ * Minimal `Worksheet`-shaped proxy used exclusively to back the `Chart`
+ * instance returned from {@link Chartsheet.chart}.
+ *
+ * A chartsheet is a top-level sheet that hosts a single chart without a
+ * surrounding grid — there are no rows, columns, tables, merges, or
+ * drawings underneath it. `Chart`, however, assumes it lives inside a
+ * `Worksheet` so it can walk up to the workbook, copy relationship
+ * sidecars, and compute anchor geometry.
+ *
+ * Previous versions fabricated an empty `{ workbook, name } as any` to
+ * satisfy that type. That escape hatch was a correctness trap: calling
+ * {@link Chart.copyTo} or anything that invoked `worksheet.getRow` on a
+ * chartsheet-backed Chart would throw because the underlying object had
+ * none of the real methods.
+ *
+ * `ChartsheetChartHost` replaces the cast with a first-class proxy that:
+ *   - forwards the `workbook` pointer so `Chart` can reach its model,
+ *     sidecars, and copyChartSidecars helper;
+ *   - reports a synthetic `id`/`name` so diagnostics stay sensible;
+ *   - throws a clear, descriptive error from every grid-centric method so
+ *     any accidental reach through fails loudly instead of silently
+ *     corrupting state (`getRow`, `addRow`, `getColumn`, `addTable`, …).
+ *
+ * Callers should prefer {@link Chartsheet.chartModel} /
+ * {@link Chartsheet.chartExModel} to reach the underlying data directly.
+ */
+class ChartsheetChartHost {
+    constructor(workbook, chartsheetId, chartsheetName) {
+        this.id = chartsheetId;
+        this.name = chartsheetName;
+        this.workbook = workbook;
+    }
+    _unsupported(method) {
+        throw new Error(`${method}() is not supported on a Chart attached to a chartsheet. ` +
+            `Use the Chartsheet APIs (chartsheet.chartModel, chartsheet.replaceChart, …) instead.`);
+    }
+    // Grid operations — explicitly fail fast rather than silently returning
+    // undefined-ish values that could feed bad data into anchor math.
+    getRow(_rowNumber) {
+        this._unsupported("Worksheet.getRow");
+    }
+    addRow() {
+        this._unsupported("Worksheet.addRow");
+    }
+    addRows() {
+        this._unsupported("Worksheet.addRows");
+    }
+    getColumn(_colNumber) {
+        this._unsupported("Worksheet.getColumn");
+    }
+    getCell() {
+        this._unsupported("Worksheet.getCell");
+    }
+    addTable() {
+        this._unsupported("Worksheet.addTable");
+    }
+    getTables() {
+        this._unsupported("Worksheet.getTables");
+    }
+}
+class Chartsheet {
+    constructor(model, workbook) {
+        this._model = model;
+        this._workbook = workbook;
+    }
+    get id() {
+        return this._model.id;
+    }
+    get sheetNo() {
+        return this._model.sheetNo;
+    }
+    get name() {
+        return this._model.name;
+    }
+    set name(value) {
+        // Go through the workbook's unified validator so a chartsheet can
+        // never silently land on a name that collides with a worksheet (or
+        // another chartsheet), includes illegal characters, or exceeds
+        // Excel's 31-char limit. Previously this setter just wrote
+        // `this._model.name = value` verbatim, letting callers corrupt the
+        // model into a state Excel would reject on reopen.
+        if (this._workbook) {
+            this._model.name = this._workbook.validateSheetName(value, this._model);
+        }
+        else {
+            this._model.name = value;
+        }
+    }
+    get state() {
+        return this._model.state;
+    }
+    set state(value) {
+        this._model.state = value;
+    }
+    get chartNumber() {
+        return this._model.chartNumber;
+    }
+    get chartExNumber() {
+        return this._model.chartExNumber;
+    }
+    get chartModel() {
+        return this._model.chartNumber
+            ? this._workbook?.getChartEntry(this._model.chartNumber)?.model
+            : undefined;
+    }
+    get chartExModel() {
+        return this._model.chartExNumber
+            ? this._workbook?.getChartExStructuredEntry(this._model.chartExNumber)?.model
+            : undefined;
+    }
+    /**
+     * Return the `Chart` wrapper for this chartsheet's single chart.
+     *
+     * The wrapper's `.worksheet` field is a {@link ChartsheetChartHost}
+     * rather than a real `Worksheet` — grid operations on it will throw a
+     * descriptive error. For anything grid-related, use the underlying
+     * {@link chartModel}/{@link chartExModel} directly or go through the
+     * `Chartsheet` methods ({@link replaceChart}, {@link rename}, …).
+     */
+    get chart() {
+        if (!this._workbook || (!this._model.chartNumber && !this._model.chartExNumber)) {
+            return undefined;
+        }
+        const host = new ChartsheetChartHost(this._workbook, this._model.id, this._model.name);
+        // The `Chart` constructor types its first argument as `Worksheet`, but
+        // internally it only touches `worksheet.workbook`, `worksheet.id`, and
+        // `worksheet.name` from that position (plus anchor helpers that we've
+        // stubbed above). Casting is safe here because the host deliberately
+        // implements that exact contract and loudly rejects anything else.
+        return getChartSupport().createChart(host, { chartNumber: this._model.chartNumber, chartExNumber: this._model.chartExNumber }, CHARTSHEET_ANCHOR_RANGE);
+    }
+    get isChartEx() {
+        return !!this._model.chartExNumber;
+    }
+    get model() {
+        return this._model;
+    }
+    get pageMargins() {
+        return this._model.pageMargins;
+    }
+    set pageMargins(value) {
+        this._model.pageMargins = value;
+    }
+    get pageSetup() {
+        return this._model.pageSetup;
+    }
+    set pageSetup(value) {
+        this._model.pageSetup = value;
+    }
+    get tabSelected() {
+        return this._model.tabSelected;
+    }
+    set tabSelected(value) {
+        this._model.tabSelected = value;
+    }
+    get zoomScale() {
+        return this._model.zoomScale;
+    }
+    set zoomScale(value) {
+        this._model.zoomScale = value;
+    }
+    get workbookViewId() {
+        return this._model.workbookViewId;
+    }
+    set workbookViewId(value) {
+        this._model.workbookViewId = value;
+    }
+    get zoomToFit() {
+        return this._model.zoomToFit;
+    }
+    set zoomToFit(value) {
+        this._model.zoomToFit = value;
+    }
+    rename(name) {
+        return this._workbook?.renameChartsheet(this.name, name) ?? false;
+    }
+    remove() {
+        return this._workbook?.removeChartsheet(this.name) ?? false;
+    }
+    copy(name) {
+        return this._workbook?.copyChartsheet(this.name, name);
+    }
+    replaceChart(chart) {
+        return this._workbook?.replaceChartsheetChart(this.name, chart) ?? false;
+    }
+}
+export { Chartsheet };

package/dist/esm/modules/excel/defined-names.js

@@ -218,6 +218,7 @@ class DefinedNames {
         this.matrixMap = {};
         this.formulaMap = {};
         this.localSheetIdMap = {};
+        this.hiddenMap = {};
         this.opaqueMap = {};
         this.nameForKey = {};
         this._explicitProbe = probe ?? null;
@@ -239,6 +240,29 @@ class DefinedNames {
         this.nameForKey[name] = name;
         this.addEx(location, name);
     }
+    /**
+     * Register a hidden defined name that maps a chartEx `_xlchart.vN.M`
+     * pointer to a worksheet range. Excel emits one of these for every
+     * data reference in a chartEx chart:
+     *
+     *   <definedName name="_xlchart.v1.0" hidden="1">Sheet1!$A$1:$A$3</definedName>
+     *
+     * The chartEx then references `_xlchart.v1.0` from its `<cx:f>`
+     * element instead of the worksheet range directly. Direct sheet
+     * references in `<cx:f>` are rejected by Excel 2016+ with
+     * "Removed Part: /xl/drawings/drawingN.xml (Drawing shape)" on
+     * load, so chartEx data MUST go through this indirection.
+     *
+     * Same semantics as `add()` but also marks the name `hidden` so
+     * it does not show up in Excel's Name Manager UI.
+     *
+     * @param locStr - Worksheet reference (e.g. `"Sheet1!$A$1:$A$3"`)
+     * @param name   - Defined name to register (e.g. `"_xlchart.v1.0"`)
+     */
+    addHidden(locStr, name) {
+        this.add(locStr, name);
+        this.hiddenMap[name] = true;
+    }
     addEx(location, name) {
         const matrix = this.getMatrix(name);
         if ("top" in location) {
@@ -516,10 +540,15 @@ class DefinedNames {
             .map(([sKey, matrix]) => {
             const result = this.getRanges(sKey, matrix);
             const localSheetId = this.localSheetIdMap[sKey];
+            const hidden = this.hiddenMap[sKey];
+            const out = { ...result };
             if (localSheetId !== undefined) {
-                return { ...result, localSheetId };
+                out.localSheetId = localSheetId;
             }
-            return result;
+            if (hidden) {
+                out.hidden = true;
+            }
+            return out;
         })
             .filter((definedName) => definedName.ranges.length);
         // Formula-based names from formulaMap (only include names not already in matrixMap)
@@ -534,20 +563,27 @@ class DefinedNames {
             };
             const localSheetId = this.localSheetIdMap[sKey];
             if (localSheetId !== undefined) {
-                return { ...result, localSheetId };
+                result.localSheetId = localSheetId;
+            }
+            if (this.hiddenMap[sKey]) {
+                result.hidden = true;
             }
             return result;
         });
         // Opaque names — rawText preserved for round-trip
         const opaqueNames = Object.entries(this.opaqueMap).map(([sKey, entry]) => {
             const bareName = this.nameForKey[sKey] ?? sKey;
-            return {
+            const out = {
                 name: bareName,
                 ranges: [],
                 rawText: entry.rawText,
                 localSheetId: entry.localSheetId,
                 kind: "opaque"
             };
+            if (this.hiddenMap[sKey]) {
+                out.hidden = true;
+            }
+            return out;
         });
         return [...cellNames, ...formulaNames, ...opaqueNames];
     }
@@ -563,6 +599,7 @@ class DefinedNames {
         const matrixMap = (this.matrixMap = {});
         const formulaMap = (this.formulaMap = {});
         const localSheetIdMap = (this.localSheetIdMap = {});
+        const hiddenMap = (this.hiddenMap = {});
         const opaqueMap = (this.opaqueMap = {});
         const nameForKeyMap = (this.nameForKey = {});
         // Resolve probe lazily: a caller may have constructed the Workbook
@@ -577,6 +614,9 @@ class DefinedNames {
             if (definedName.localSheetId !== undefined) {
                 localSheetIdMap[sKey] = definedName.localSheetId;
             }
+            if (definedName.hidden) {
+                hiddenMap[sKey] = true;
+            }
             // Programmatic API path: formulaExpression already set and no rawText
             if (definedName.formulaExpression && definedName.rawText === undefined) {
                 formulaMap[sKey] = definedName.formulaExpression;

package/dist/esm/modules/excel/errors.js

@@ -145,6 +145,15 @@ export class PivotTableError extends ExcelError {
         this.name = "PivotTableError";
     }
 }
+/**
+ * Error thrown when chart configuration is invalid.
+ */
+export class ChartOptionsError extends ExcelError {
+    constructor() {
+        super(...arguments);
+        this.name = "ChartOptionsError";
+    }
+}
 /**
  * Error thrown when table configuration or operation is invalid.
  */

package/dist/esm/modules/excel/form-control.js

@@ -51,6 +51,23 @@ class FormCheckbox {
             print: options?.print ?? false
         };
     }
+    /**
+     * Rebuild a FormCheckbox from a previously-serialised model (e.g. round-tripped
+     * via `worksheet.model`). The model is adopted as-is; no range parsing or shape
+     * id reassignment is performed.
+     */
+    static fromModel(worksheet, model) {
+        const cb = Object.create(FormCheckbox.prototype);
+        cb.worksheet = worksheet;
+        // Defensive shallow clone: the caller should not be able to mutate the
+        // underlying anchor objects through the original reference.
+        cb.model = {
+            ...model,
+            tl: { ...model.tl },
+            br: { ...model.br }
+        };
+        return cb;
+    }
     /**
      * Get the checked state
      */