@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/browser/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/browser/modules/excel/chart-host-registry.d.ts

@@ -0,0 +1,157 @@
+/**
+ * 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.
+ */
+import type { fillChartCaches, fillChartExCaches } from "./chart/cache-populator.js";
+import type { Chart, ChartAnchorModel, buildChartModel } from "./chart/chart.js";
+import type { chartExOptionsFromRows, chartExOptionsFromTable, chartOptionsFromRows, chartOptionsFromTable, seriesFromColumns } from "./chart/chart-api.js";
+import type { buildComboChartModel } from "./chart/chart-builder.js";
+import type { buildChartExModel } from "./chart/chart-ex-builder.js";
+import type { parseChartEx } from "./chart/chart-ex-parser.js";
+import type { canRenderChartExAsVectorPdf, drawChartExPdf, renderChartEx, renderChartExLegendXml, renderChartExPng, rewriteChartExDataRefsToDefinedNames } from "./chart/chart-ex-renderer.js";
+import type { resolvePendingChartImages } from "./chart/chart-images.js";
+import type { applyChartExPreset, applyChartPreset } from "./chart/chart-presets.js";
+import type { drawChartPdf, renderChartPng } from "./chart/chart-renderer.js";
+import type { buildChartColors, buildChartStyle } from "./chart/chart-sidecar.js";
+import type { themeIndexToName } from "./chart/chart-utils.js";
+import type { AddChartRange } from "./chart/types.js";
+import type { Worksheet } from "./worksheet.js";
+import type { ChartSpaceXform } from "./xlsx/xform/chart/chart-space-xform.js";
+/**
+ * Runtime chart functions the excel module needs from the chart
+ * module. Populated by `installChartSupport()` from
+ * `@cj-tech-master/excelts/chart`.
+ *
+ * Using `typeof <fn>` keeps the signatures in lockstep with the real
+ * implementations — add an argument to `buildChartModel` and this
+ * interface updates automatically, as do all call sites. Consumers who
+ * provide a custom chart-support implementation (test doubles, mock
+ * providers) get a type error when signatures drift.
+ *
+ * The `Chart` class constructor is wrapped in a factory function
+ * (`createChart`) rather than exposed as a raw constructor reference:
+ * `new (getChartSupport().Chart)(...)` reads poorly at the call site,
+ * `getChartSupport().createChart(...)` reads cleanly.
+ */
+export interface ChartSupport {
+    readonly buildChartModel: typeof buildChartModel;
+    readonly buildComboChartModel: typeof buildComboChartModel;
+    readonly buildChartExModel: typeof buildChartExModel;
+    readonly applyChartPreset: typeof applyChartPreset;
+    readonly applyChartExPreset: typeof applyChartExPreset;
+    readonly fillChartCaches: typeof fillChartCaches;
+    readonly fillChartExCaches: typeof fillChartExCaches;
+    readonly resolvePendingChartImages: typeof resolvePendingChartImages;
+    readonly buildChartStyle: typeof buildChartStyle;
+    readonly buildChartColors: typeof buildChartColors;
+    /**
+     * Factory for a `Chart` instance. Preferred over exposing the raw
+     * constructor because `new (getChartSupport().Chart)(...)` is
+     * awkward at call sites.
+     *
+     * Accepts either an `AddChartRange` (the public addChart API
+     * surface: A1-notation strings, tl/br pairs, tl+ext, or pos+ext)
+     * **or** a `ChartAnchorModel["range"]` (the model-shaped form
+     * re-hydrated from an XLSX drawing anchor). The Chart constructor
+     * accepts both and routes through the same `parseRange` helper.
+     */
+    readonly createChart: (worksheet: Worksheet, ids: {
+        chartNumber?: number;
+        chartExNumber?: number;
+    }, range: AddChartRange | ChartAnchorModel["range"]) => Chart;
+    readonly chartOptionsFromTable: typeof chartOptionsFromTable;
+    readonly chartOptionsFromRows: typeof chartOptionsFromRows;
+    readonly chartExOptionsFromTable: typeof chartExOptionsFromTable;
+    readonly chartExOptionsFromRows: typeof chartExOptionsFromRows;
+    readonly seriesFromColumns: typeof seriesFromColumns;
+    readonly parseChartEx: typeof parseChartEx;
+    readonly renderChartEx: typeof renderChartEx;
+    readonly renderChartExLegendXml: typeof renderChartExLegendXml;
+    readonly rewriteChartExDataRefsToDefinedNames: typeof rewriteChartExDataRefsToDefinedNames;
+    readonly themeIndexToName: typeof themeIndexToName;
+    /**
+     * Factory for the classic-chart XLSX xform (`c:chartSpace` parser +
+     * writer). `chart-space-xform.ts` itself statically imports
+     * `chart-utils` and `shape-properties` from the chart module, so
+     * exposing it through the registry ensures a consumer who never
+     * installs chart support also never pulls those chart files into
+     * their bundle via the xform graph.
+     */
+    readonly createChartSpaceXform: () => ChartSpaceXform;
+    readonly drawChartPdf: typeof drawChartPdf;
+    readonly drawChartExPdf: typeof drawChartExPdf;
+    readonly renderChartPng: typeof renderChartPng;
+    readonly renderChartExPng: typeof renderChartExPng;
+    readonly canRenderChartExAsVectorPdf: typeof canRenderChartExAsVectorPdf;
+}
+/**
+ * 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 declare function registerChartSupport(support: ChartSupport | null): void;
+/** Returns true when chart support has been installed. */
+export declare function hasChartSupport(): boolean;
+/**
+ * Retrieve the installed chart support. Throws a descriptive error if
+ * no chart support is installed.
+ */
+export declare function getChartSupport(): ChartSupport;
+/**
+ * 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 declare function tryGetChartSupport(): ChartSupport | null;

package/dist/browser/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/browser/modules/excel/chartsheet.d.ts

@@ -0,0 +1,102 @@
+import type { Chart } from "./chart/chart.js";
+import type { AddChartExOptions, ChartExModel } from "./chart/chart-ex-types.js";
+import type { AddChartOptions, AddComboChartOptions, ChartModel } from "./chart/types.js";
+import type { ChartsheetModel } from "./xlsx/xform/sheet/chartsheet-xform.js";
+export interface ChartsheetViewOptions {
+    /** Whether the chartsheet tab is selected in the workbook view. */
+    tabSelected?: boolean;
+    /** Zoom scale percentage. */
+    zoomScale?: number;
+    /**
+     * 0-based index into the workbook's `<bookViews>` list that this
+     * chartsheet view is bound to. Defaults to 0 (the primary view).
+     */
+    workbookViewId?: number;
+    /**
+     * When true the chartsheet scales to fill the window. Matches the
+     * OOXML `<sheetView zoomToFit="1"/>` attribute.
+     */
+    zoomToFit?: boolean;
+}
+export interface ChartsheetOptions extends ChartsheetViewOptions {
+    /** Sheet visibility state. */
+    state?: "visible" | "hidden" | "veryHidden";
+    /** Page margins for the chartsheet. */
+    pageMargins?: ChartsheetModel["pageMargins"];
+    /** Page setup for the chartsheet (CT_CsPageSetup). */
+    pageSetup?: ChartsheetModel["pageSetup"];
+}
+export interface AddChartsheetOptions extends ChartsheetOptions {
+    /** Chart to place on the chartsheet. */
+    chart: AddChartOptions | AddComboChartOptions | AddChartExOptions;
+}
+export interface AddPivotChartsheetOptions extends ChartsheetOptions {
+    /** Classic chart or combo chart to place on the chartsheet as a pivot chart. */
+    chart: AddChartOptions | AddComboChartOptions;
+}
+declare class Chartsheet {
+    private readonly _model;
+    private readonly _workbook?;
+    constructor(model: ChartsheetModel, workbook?: ChartsheetWorkbook);
+    get id(): number;
+    get sheetNo(): number;
+    get name(): string;
+    set name(value: string);
+    get state(): ChartsheetModel["state"];
+    set state(value: ChartsheetModel["state"]);
+    get chartNumber(): number | undefined;
+    get chartExNumber(): number | undefined;
+    get chartModel(): ChartModel | undefined;
+    get chartExModel(): ChartExModel | 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(): Chart | undefined;
+    get isChartEx(): boolean;
+    get model(): ChartsheetModel;
+    get pageMargins(): ChartsheetModel["pageMargins"];
+    set pageMargins(value: ChartsheetModel["pageMargins"]);
+    get pageSetup(): ChartsheetModel["pageSetup"];
+    set pageSetup(value: ChartsheetModel["pageSetup"]);
+    get tabSelected(): boolean | undefined;
+    set tabSelected(value: boolean | undefined);
+    get zoomScale(): number | undefined;
+    set zoomScale(value: number | undefined);
+    get workbookViewId(): number | undefined;
+    set workbookViewId(value: number | undefined);
+    get zoomToFit(): boolean | undefined;
+    set zoomToFit(value: boolean | undefined);
+    rename(name: string): boolean;
+    remove(): boolean;
+    copy(name?: string): Chartsheet | undefined;
+    replaceChart(chart: AddChartsheetOptions["chart"]): boolean;
+}
+interface ChartsheetWorkbook {
+    getChartEntry(chartNumber: number): {
+        model: ChartModel;
+    } | undefined;
+    getChartExStructuredEntry(chartExNumber: number): {
+        model: ChartExModel;
+    } | undefined;
+    renameChartsheet(nameOrIndex: string | number, name: string): boolean;
+    removeChartsheet(nameOrIndex: string | number): boolean;
+    copyChartsheet(nameOrIndex: string | number, name?: string): Chartsheet | undefined;
+    replaceChartsheetChart(nameOrIndex: string | number, chart: AddChartsheetOptions["chart"]): boolean;
+    /**
+     * Validate a sheet name against Excel's unified namespace (both
+     * worksheets and chartsheets). See `Workbook.validateSheetName` for
+     * the full contract. Declared here so `Chartsheet.name` setter can
+     * route through it without widening the narrow host interface to
+     * the full `Workbook` type.
+     */
+    validateSheetName(name: string, existing?: {
+        name: string;
+    }): string;
+}
+export { Chartsheet };

package/dist/browser/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/browser/modules/excel/defined-names.d.ts

@@ -26,6 +26,14 @@ interface DefinedNameModel {
      * - "opaque": unrecognised content preserved for round-trip — stored in opaqueMap
      */
     kind?: "reference" | "formula" | "opaque";
+    /**
+     * `definedName/@hidden` — when `true`, emits `hidden="1"` on the
+     * XML element. Used by chartEx `_xlchart.vN.M` defined names that
+     * Excel creates automatically for every chartEx data reference;
+     * these names are infrastructure, never intended for users, so
+     * Excel hides them from the Name Manager UI.
+     */
+    hidden?: boolean;
 }
 /** Stored entry for an opaque (unrecognised) defined name. */
 interface OpaqueEntry {
@@ -43,6 +51,13 @@ declare class DefinedNames {
      * If a key is not in this map, the name is workbook-scoped (global).
      */
     localSheetIdMap: Record<string, number>;
+    /**
+     * Tracks the `hidden` flag for each storage key. Used by chartEx
+     * `_xlchart.vN.M` infrastructure names — Excel emits them with
+     * `hidden="1"` to suppress the Name Manager UI. A missing key
+     * means "not hidden" (the default).
+     */
+    hiddenMap: Record<string, boolean>;
     /**
      * Opaque defined names: storageKey → original text + optional localSheetId.
      */
@@ -70,6 +85,26 @@ declare class DefinedNames {
     constructor(probe?: SyntaxProbe);
     getMatrix(name: string): CellMatrix;
     add(locStr: string, name: string): void;
+    /**
+     * 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: string, name: string): void;
     addEx(location: CellLocation, name: string): void;
     /**
      * Register a formula-based defined name.