@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/utils/string-buf.d.ts

@@ -0,0 +1,42 @@
+/**
+ * StringBuf - Cross-Platform String Buffer
+ *
+ * Efficient string builder that accumulates UTF-8 encoded bytes into a single
+ * `Uint8Array`. Designed for hot paths that build large XML / text payloads
+ * (XLSX worksheet writers, streaming DOCX writer) where naïve `string +=`
+ * concatenation triggers O(n²) re-allocations.
+ *
+ * Works identically in Node.js and Browser environments — uses only
+ * `TextEncoder` and `Uint8Array`.
+ */
+interface StringBufOptions {
+    /** Initial capacity in bytes (default: 16384). */
+    size?: number;
+    /**
+     * Encoding label, accepted for API symmetry. Only UTF-8 is supported by
+     * `TextEncoder`, so this option is ignored.
+     */
+    encoding?: string;
+}
+/**
+ * Efficient string builder backed by a growable `Uint8Array`.
+ */
+declare class StringBuf {
+    private _buf;
+    private _inPos;
+    private _buffer;
+    constructor(options?: StringBufOptions);
+    get length(): number;
+    get capacity(): number;
+    get buffer(): Uint8Array;
+    /** Return a snapshot of the bytes written so far. Cached until next mutation. */
+    toBuffer(): Uint8Array;
+    reset(position?: number): void;
+    private _grow;
+    /** Append a string, encoded as UTF-8. */
+    addText(text: string): void;
+    /** Append the contents of another StringBuf without re-encoding. */
+    addStringBuf(inBuf: StringBuf): void;
+}
+export { StringBuf };
+export type { StringBufOptions };

package/dist/browser/utils/string-buf.js

@@ -0,0 +1,89 @@
+/**
+ * StringBuf - Cross-Platform String Buffer
+ *
+ * Efficient string builder that accumulates UTF-8 encoded bytes into a single
+ * `Uint8Array`. Designed for hot paths that build large XML / text payloads
+ * (XLSX worksheet writers, streaming DOCX writer) where naïve `string +=`
+ * concatenation triggers O(n²) re-allocations.
+ *
+ * Works identically in Node.js and Browser environments — uses only
+ * `TextEncoder` and `Uint8Array`.
+ */
+const encoder = new TextEncoder();
+/**
+ * Efficient string builder backed by a growable `Uint8Array`.
+ */
+class StringBuf {
+    constructor(options) {
+        this._buf = new Uint8Array((options && options.size) || 16384);
+        this._inPos = 0;
+        this._buffer = undefined;
+    }
+    get length() {
+        return this._inPos;
+    }
+    get capacity() {
+        return this._buf.length;
+    }
+    get buffer() {
+        return this._buf;
+    }
+    /** Return a snapshot of the bytes written so far. Cached until next mutation. */
+    toBuffer() {
+        if (!this._buffer) {
+            this._buffer = this._buf.slice(0, this._inPos);
+        }
+        return this._buffer;
+    }
+    reset(position) {
+        position = position ?? 0;
+        this._buffer = undefined;
+        this._inPos = position;
+    }
+    _grow(min) {
+        let size = this._buf.length * 2;
+        while (size < min) {
+            size *= 2;
+        }
+        const buf = new Uint8Array(size);
+        buf.set(this._buf);
+        this._buf = buf;
+    }
+    /** Append a string, encoded as UTF-8. */
+    addText(text) {
+        this._buffer = undefined;
+        // Optimistically reserve 1 byte per char (true for ASCII; multi-byte
+        // chars trigger the slow path below).
+        const optimistic = this._inPos + text.length;
+        if (optimistic > this._buf.length - 4) {
+            this._grow(optimistic);
+        }
+        // `encodeInto` writes directly into the buffer, avoiding the intermediate
+        // Uint8Array allocation that `encoder.encode()` creates.
+        const target = this._buf.subarray(this._inPos);
+        const result = encoder.encodeInto(text, target);
+        if (result.read < text.length) {
+            // Multi-byte chars exceeded the optimistic estimate.
+            // Worst case: 3 bytes per remaining char.
+            const remaining = text.length - result.read;
+            this._grow(this._inPos + result.written + remaining * 3);
+            const result2 = encoder.encodeInto(text.substring(result.read), this._buf.subarray(this._inPos + result.written));
+            this._inPos += result.written + result2.written;
+        }
+        else {
+            this._inPos += result.written;
+        }
+    }
+    /** Append the contents of another StringBuf without re-encoding. */
+    addStringBuf(inBuf) {
+        if (inBuf.length) {
+            this._buffer = undefined;
+            if (this.length + inBuf.length > this.capacity) {
+                this._grow(this.length + inBuf.length);
+            }
+            this._buf.set(inBuf._buf.subarray(0, inBuf.length), this._inPos);
+            this._inPos += inBuf.length;
+        }
+    }
+}
+export { StringBuf };

package/dist/browser/utils/theme-colors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * OOXML Theme Color Resolution — shared between Excel and Word modules.
+ *
+ * Provides utilities for resolving theme color references with tint/shade
+ * transformations per the ECMA-376 color model.
+ */
+/** Standard OOXML theme color names (scheme keys in theme1.xml). */
+export type OoxmlThemeColorName = "dk1" | "lt1" | "dk2" | "lt2" | "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "hlink" | "folHlink";
+/**
+ * Map from OOXML property attribute values to theme scheme keys.
+ *
+ * Word/Excel run/paragraph/cell properties use long-form names ("dark1",
+ * "light1", "hyperlink") while the theme XML stores short-form keys
+ * ("dk1", "lt1", "hlink"). This map normalises both forms.
+ */
+export declare const THEME_COLOR_ATTRIBUTE_MAP: Record<string, OoxmlThemeColorName>;
+/**
+ * Apply a tint (lighten toward white) to a hex color.
+ *
+ * OOXML tint formula: `newComponent = component + (255 - component) * tint`
+ * where tint ∈ [0, 1]. tint=0 → original, tint=1 → white.
+ *
+ * @param hex - 6-character hex color string (no "#" prefix).
+ * @param tint - Tint value in range [0, 1].
+ * @returns Tinted 6-character hex color string.
+ */
+export declare function applyTint(hex: string, tint: number): string;
+/**
+ * Apply a shade (darken toward black) to a hex color.
+ *
+ * OOXML shade formula: `newComponent = component * shade`
+ * where shade ∈ [0, 1]. shade=1 → original, shade=0 → black.
+ *
+ * @param hex - 6-character hex color string (no "#" prefix).
+ * @param shade - Shade value in range [0, 1].
+ * @returns Shaded 6-character hex color string.
+ */
+export declare function applyShade(hex: string, shade: number): string;
+/**
+ * Resolve a theme color reference to a hex color string.
+ *
+ * Looks up the theme color by attribute name (normalising long-form names
+ * like "dark1" to scheme keys like "dk1"), then applies optional tint or
+ * shade transformation.
+ *
+ * @param themeColorName - The theme color attribute value (e.g. "accent1", "dark1", "dk1").
+ * @param colors - The theme color scheme (scheme key → 6-char hex mapping).
+ * @param tint - Optional tint value in [0, 1]. Values > 1 are treated as
+ *               raw bytes (0-255) and normalised by dividing by 255.
+ * @param shade - Optional shade value in [0, 1]. Values > 1 are treated as
+ *                raw bytes (0-255) and normalised by dividing by 255.
+ * @returns Resolved 6-character hex color string, or undefined if the theme
+ *          color name cannot be found in the provided scheme.
+ */
+export declare function resolveOoxmlThemeColor(themeColorName: string, colors: Readonly<Record<string, string>>, tint?: number, shade?: number): string | undefined;

package/dist/browser/utils/theme-colors.js

@@ -0,0 +1,120 @@
+/**
+ * OOXML Theme Color Resolution — shared between Excel and Word modules.
+ *
+ * Provides utilities for resolving theme color references with tint/shade
+ * transformations per the ECMA-376 color model.
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Map from OOXML property attribute values to theme scheme keys.
+ *
+ * Word/Excel run/paragraph/cell properties use long-form names ("dark1",
+ * "light1", "hyperlink") while the theme XML stores short-form keys
+ * ("dk1", "lt1", "hlink"). This map normalises both forms.
+ */
+export const THEME_COLOR_ATTRIBUTE_MAP = {
+    dark1: "dk1",
+    light1: "lt1",
+    dark2: "dk2",
+    light2: "lt2",
+    accent1: "accent1",
+    accent2: "accent2",
+    accent3: "accent3",
+    accent4: "accent4",
+    accent5: "accent5",
+    accent6: "accent6",
+    hyperlink: "hlink",
+    followedHyperlink: "folHlink",
+    // Also accept direct scheme keys
+    dk1: "dk1",
+    lt1: "lt1",
+    dk2: "dk2",
+    lt2: "lt2",
+    hlink: "hlink",
+    folHlink: "folHlink"
+};
+// =============================================================================
+// Tint / Shade transformations
+// =============================================================================
+/**
+ * Apply a tint (lighten toward white) to a hex color.
+ *
+ * OOXML tint formula: `newComponent = component + (255 - component) * tint`
+ * where tint ∈ [0, 1]. tint=0 → original, tint=1 → white.
+ *
+ * @param hex - 6-character hex color string (no "#" prefix).
+ * @param tint - Tint value in range [0, 1].
+ * @returns Tinted 6-character hex color string.
+ */
+export function applyTint(hex, tint) {
+    const r = parseInt(hex.slice(0, 2), 16);
+    const g = parseInt(hex.slice(2, 4), 16);
+    const b = parseInt(hex.slice(4, 6), 16);
+    const nr = Math.round(r + (255 - r) * tint);
+    const ng = Math.round(g + (255 - g) * tint);
+    const nb = Math.round(b + (255 - b) * tint);
+    return toHex2(nr) + toHex2(ng) + toHex2(nb);
+}
+/**
+ * Apply a shade (darken toward black) to a hex color.
+ *
+ * OOXML shade formula: `newComponent = component * shade`
+ * where shade ∈ [0, 1]. shade=1 → original, shade=0 → black.
+ *
+ * @param hex - 6-character hex color string (no "#" prefix).
+ * @param shade - Shade value in range [0, 1].
+ * @returns Shaded 6-character hex color string.
+ */
+export function applyShade(hex, shade) {
+    const r = parseInt(hex.slice(0, 2), 16);
+    const g = parseInt(hex.slice(2, 4), 16);
+    const b = parseInt(hex.slice(4, 6), 16);
+    const nr = Math.round(r * shade);
+    const ng = Math.round(g * shade);
+    const nb = Math.round(b * shade);
+    return toHex2(nr) + toHex2(ng) + toHex2(nb);
+}
+// =============================================================================
+// Theme Color Resolution
+// =============================================================================
+/**
+ * Resolve a theme color reference to a hex color string.
+ *
+ * Looks up the theme color by attribute name (normalising long-form names
+ * like "dark1" to scheme keys like "dk1"), then applies optional tint or
+ * shade transformation.
+ *
+ * @param themeColorName - The theme color attribute value (e.g. "accent1", "dark1", "dk1").
+ * @param colors - The theme color scheme (scheme key → 6-char hex mapping).
+ * @param tint - Optional tint value in [0, 1]. Values > 1 are treated as
+ *               raw bytes (0-255) and normalised by dividing by 255.
+ * @param shade - Optional shade value in [0, 1]. Values > 1 are treated as
+ *                raw bytes (0-255) and normalised by dividing by 255.
+ * @returns Resolved 6-character hex color string, or undefined if the theme
+ *          color name cannot be found in the provided scheme.
+ */
+export function resolveOoxmlThemeColor(themeColorName, colors, tint, shade) {
+    const key = THEME_COLOR_ATTRIBUTE_MAP[themeColorName] ?? themeColorName;
+    const base = colors[key];
+    if (!base) {
+        return undefined;
+    }
+    if (tint !== undefined && tint !== 0) {
+        const normalizedTint = tint > 1 ? tint / 255 : tint;
+        return applyTint(base, normalizedTint);
+    }
+    if (shade !== undefined && shade !== 0) {
+        const normalizedShade = shade > 1 ? shade / 255 : shade;
+        return applyShade(base, normalizedShade);
+    }
+    return base;
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function toHex2(n) {
+    const h = Math.max(0, Math.min(255, n)).toString(16);
+    return h.length < 2 ? "0" + h : h;
+}

package/dist/cjs/modules/archive/compression/streaming-compress.browser.js

@@ -52,6 +52,15 @@ function hasDeflateRaw() {
 /**
  * Base streaming codec with unified lifecycle management.
  * Backend can emit events via the returned codec reference.
+ *
+ * Backpressure: each `write()` chains a deflate task onto `writeChain`.
+ * Without throttling, a fast producer could enqueue thousands of tasks
+ * (each retaining its input chunk) before the backend catches up. To
+ * surface backpressure to the caller, we count pending writes; once the
+ * count reaches `HIGH_WATER_MARK`, `write()` returns `false`. When the
+ * count drops back below the mark, we emit `'drain'` so callers using
+ * the standard Node Writable contract (`pipe()` / `pipeline()`) can
+ * resume. This keeps memory bounded on slow backends or slow consumers.
  */
 class AsyncStreamCodec extends event_emitter_1.EventEmitter {
     constructor() {
@@ -60,6 +69,8 @@ class AsyncStreamCodec extends event_emitter_1.EventEmitter {
         this.destroyed = false;
         this.writeChain = Promise.resolve();
         this._backend = null;
+        this._pendingWrites = 0;
+        this._needsDrain = false;
     }
     setBackend(backend) {
         this._backend = backend;
@@ -79,6 +90,7 @@ class AsyncStreamCodec extends event_emitter_1.EventEmitter {
         if (!backend) {
             throw new Error("Backend not initialized");
         }
+        this._pendingWrites++;
         const promise = this.writeChain.then(() => backend.write(chunk));
         this.writeChain = promise;
         promise
@@ -91,7 +103,20 @@ class AsyncStreamCodec extends event_emitter_1.EventEmitter {
             if (!this.destroyed) {
                 handleError(this, err, callback);
             }
+        })
+            .finally(() => {
+            this._pendingWrites--;
+            if (this._needsDrain &&
+                this._pendingWrites < AsyncStreamCodec.HIGH_WATER_MARK &&
+                !this.destroyed) {
+                this._needsDrain = false;
+                this.emit("drain");
+            }
         });
+        if (this._pendingWrites >= AsyncStreamCodec.HIGH_WATER_MARK) {
+            this._needsDrain = true;
+            return false;
+        }
         return true;
     }
     end(callback) {
@@ -118,6 +143,10 @@ class AsyncStreamCodec extends event_emitter_1.EventEmitter {
         }
     }
 }
+// Allow up to this many in-flight chunks before signalling backpressure.
+// 16 chunks × typical 64 KiB ≈ 1 MiB of in-flight retention, enough to
+// saturate the deflate backend without unbounded growth.
+AsyncStreamCodec.HIGH_WATER_MARK = 16;
 function createNativeWebStreamCodec(format, isCompress) {
     const stream = isCompress
         ? new CompressionStream(format)

package/dist/cjs/modules/archive/compression/streaming-compress.js

@@ -21,6 +21,15 @@ const _stream_1 = require("../../stream/index.js");
 /**
  * Generic wrapper around zlib streams that flushes after every write.
  * This ensures true streaming behavior - data is emitted immediately, not buffered.
+ *
+ * Backpressure note: the inner `zstream` (Node's `zlib.createDeflate*` etc)
+ * is itself a Transform, so its own `_transform` honours backpressure on
+ * the writer side. The `'data'` listener pushes into our own Transform's
+ * readable side; if a consumer is slow, our `push()` returns false but
+ * the inner zlib stream keeps emitting 'data' until its OWN HWM stops it.
+ * In the worst case, the zlib internal queue + our readable queue both
+ * fill to HWM (≈64 KiB total). For excelts's actual use (one zlib stream
+ * per ZIP entry, consumer is the zip framer which keeps up), this is fine.
  */
 class TrueStreamingZlib extends _stream_1.Transform {
     constructor(zstream) {

package/dist/cjs/modules/archive/compression/worker-pool/pool.browser.js

@@ -507,9 +507,10 @@ class WorkerPool {
      */
     _handleWorkerError(poolWorker, event) {
         const taskId = poolWorker.currentTaskId;
+        const session = poolWorker.streamSession;
         // Terminate the failed worker
         this._terminateWorker(poolWorker);
-        // Fail the current task if any
+        // Fail the current batch task if any
         if (taskId !== null) {
             const task = this._pendingTasks.get(taskId);
             if (task) {
@@ -519,6 +520,30 @@ class WorkerPool {
                 task.reject(new Error(event.message || "Worker error"));
             }
         }
+        // CRITICAL: a worker hosting a streaming session can die from an
+        // uncaught error in the worker script, OOM, CSP violation, page
+        // unload, etc. The session is NOT in `_pendingTasks` (those are
+        // batch-only) — without this, the session's `resolveStart` /
+        // slot waiter / drain waiter / `onError` are never called and the
+        // caller (AsyncStreamCodec.write/end) hangs forever. Wake every
+        // promise we own and report the error to the codec.
+        if (session) {
+            const error = new Error(event.message || "Worker terminated unexpectedly");
+            session.ended = true;
+            session.rejectStart?.(error);
+            session.rejectStart = null;
+            session.resolveStart = null;
+            this._resolveSlotWaiter(session);
+            this._resolveDrainWaiter(session);
+            try {
+                session.onError(error);
+            }
+            catch {
+                // The onError callback is user-supplied; if it throws we still
+                // want to keep cleaning up the pool.
+            }
+            poolWorker.streamSession = null;
+        }
         // Try to process remaining tasks
         this._processQueue();
     }

package/dist/cjs/modules/archive/fs/archive-file.js

@@ -1232,15 +1232,18 @@ class ArchiveFile {
      * archive.addFile("large-file.bin");
      * archive.addDirectory("./data");
      *
-     * // Stream to a file
+     * // Recommended: pipeTo() handles backpressure end-to-end.
+     * await archive.pipeTo(createWriteStream("output.zip"));
+     *
+     * // Or stream manually — REMEMBER to honor backpressure on the sink:
+     * import { once } from "node:events";
      * const writeStream = createWriteStream("output.zip");
      * for await (const chunk of archive.stream()) {
-     *   writeStream.write(chunk);
+     *   if (!writeStream.write(chunk)) {
+     *     await once(writeStream, "drain");
+     *   }
      * }
      * writeStream.end();
-     *
-     * // Or use pipeTo() for simpler file output
-     * await archive.pipeTo(createWriteStream("output.zip"));
      * ```
      */
     stream(options = {}) {
@@ -2618,23 +2621,82 @@ class ArchiveFile {
                     }
                     clearConsumedChunks();
                 }
+                // Eagerly attach an error listener so a mid-stream gzip failure is
+                // captured and surfaced (instead of becoming an uncaught exception
+                // when the listener-less Transform emits 'error' during our drain
+                // await below). Stored in a closure variable so the drain await can
+                // race against it.
+                let gzipError = null;
+                const onGzipError = (err) => {
+                    if (!gzipError) {
+                        gzipError = err;
+                    }
+                };
+                gzipStream.on("error", onGzipError);
                 // Collect gzip output
                 gzipStream.on("data", (chunk) => {
                     chunks.push(chunk);
                 });
-                // Pipe tar chunks through gzip
-                for await (const tarChunk of tarIterable) {
-                    gzipStream.write(tarChunk);
-                    // Yield any available gzip output
-                    for (const chunk of drainChunks()) {
-                        yield chunk;
+                try {
+                    // Pipe tar chunks through gzip. Honor `gzipStream.write()`'s
+                    // backpressure signal so the gzip Transform's internal buffer
+                    // can't grow unbounded if tar produces faster than gzip deflates.
+                    for await (const tarChunk of tarIterable) {
+                        if (gzipError) {
+                            // gzipError is captured as an Error (the closure annotation
+                            // says `Error | null`); rethrow rather than wrap to preserve
+                            // the original stack and message.
+                            // oxlint-disable-next-line no-throw-literal
+                            throw gzipError;
+                        }
+                        if (!gzipStream.write(tarChunk)) {
+                            // Race drain vs error so a mid-stream gzip failure rejects
+                            // promptly instead of leaving us parked on a 'drain' that
+                            // will never fire.
+                            await new Promise((resolve, reject) => {
+                                const cleanup = () => {
+                                    gzipStream.off("drain", onDrain);
+                                    gzipStream.off("error", onError);
+                                };
+                                const onDrain = () => {
+                                    cleanup();
+                                    resolve();
+                                };
+                                const onError = (err) => {
+                                    cleanup();
+                                    reject(err);
+                                };
+                                gzipStream.once("drain", onDrain);
+                                gzipStream.once("error", onError);
+                            });
+                        }
+                        // Yield any available gzip output
+                        for (const chunk of drainChunks()) {
+                            yield chunk;
+                        }
                     }
+                    // Finalize gzip stream — re-use the existing onGzipError listener
+                    // for the end() callback path, but wrap it as a Promise that
+                    // rejects on either error or accepts on end.
+                    await new Promise((resolve, reject) => {
+                        if (gzipError) {
+                            reject(gzipError);
+                            return;
+                        }
+                        const onEndError = (err) => {
+                            gzipStream.off("error", onEndError);
+                            reject(err);
+                        };
+                        gzipStream.once("error", onEndError);
+                        gzipStream.end(() => {
+                            gzipStream.off("error", onEndError);
+                            resolve();
+                        });
+                    });
+                }
+                finally {
+                    gzipStream.off("error", onGzipError);
                 }
-                // Finalize gzip stream
-                await new Promise((resolve, reject) => {
-                    gzipStream.on("error", reject);
-                    gzipStream.end(() => resolve());
-                });
                 // Yield remaining chunks
                 for (const chunk of drainChunks()) {
                     yield chunk;

package/dist/cjs/modules/archive/unzip/stream.browser.js

@@ -54,6 +54,11 @@ class BrowserInflateRaw extends _stream_1.Duplex {
         this._bytesIn = 0;
         this._bytesOut = 0;
         this._readingDone = false;
+        // Backpressure: when `push()` returns false, the reader loop parks on this
+        // resolver. `_read()` (called by Node when the consumer wants more bytes)
+        // resolves it so the loop continues. Without this, a slow consumer would
+        // cause unbounded growth of the Duplex's internal readable buffer.
+        this._readPullResolver = null;
         // Track pending write count for proper ordering
         this._pendingWrites = 0;
         this._writeFinishedPromise = null;
@@ -111,6 +116,29 @@ class BrowserInflateRaw extends _stream_1.Duplex {
             }
         });
     }
+    /**
+     * Park the reader loop until the consumer pulls more data. Resolved by
+     * the next `_read()` invocation from Node, which signals that the
+     * Duplex's readable buffer has room again.
+     */
+    _waitForReadablePull() {
+        if (this._readPullResolver) {
+            // Should not happen — only one push site at a time.
+            return Promise.resolve();
+        }
+        return new Promise(resolve => {
+            this._readPullResolver = resolve;
+        });
+    }
+    _read(_size) {
+        // Consumer wants more bytes. Wake the reader loop if it parked on
+        // backpressure.
+        const resolver = this._readPullResolver;
+        if (resolver) {
+            this._readPullResolver = null;
+            resolver();
+        }
+    }
     async _startReading() {
         if (this.reading) {
             return;
@@ -123,8 +151,14 @@ class BrowserInflateRaw extends _stream_1.Duplex {
                     break;
                 }
                 this._bytesOut += value.length;
-                // Directly push to the readable side of Duplex
-                this.push(value);
+                // Push to the Duplex's readable side. If the consumer is slow,
+                // `push()` returns false; pause our reader-loop until the consumer
+                // pulls. Without this, a fast WebStream decompressor could overrun
+                // the Duplex's readable buffer and accumulate megabytes of
+                // decompressed data with no consumer.
+                if (!this.push(value)) {
+                    await this._waitForReadablePull();
+                }
             }
         }
         catch (e) {
@@ -182,6 +216,13 @@ class BrowserInflateRaw extends _stream_1.Duplex {
             this.writer.abort(error ?? undefined).catch(() => { });
         }
         this.reader.cancel(error ?? undefined).catch(() => { });
+        // Wake the reader-loop's backpressure waiter if any so `_startReading()`
+        // can unwind cleanly instead of hanging on a never-resolved promise.
+        const resolver = this._readPullResolver;
+        if (resolver) {
+            this._readPullResolver = null;
+            resolver();
+        }
         return super.destroy(error ?? undefined);
     }
 }

package/dist/cjs/modules/excel/chart/chart-ex-builder.js

@@ -783,8 +783,13 @@ function validateChartExOptions(opts) {
         validateBinning(binning);
     }
     opts.series.forEach((series, i) => {
-        if (!series.values) {
-            throw new errors_1.ChartOptionsError(`chartEx.series[${i}].values is required.`);
+        // A series must reference its data either via a worksheet formula
+        // (`values`) or via cached literal values (`literalValues`). Headless
+        // chart pipelines (e.g. the Word `buildWordChartExXml` bridge) ship
+        // only `literalValues` because there is no underlying worksheet to
+        // reference.
+        if (!series.values && !series.literalValues?.length) {
+            throw new errors_1.ChartOptionsError(`chartEx.series[${i}].values or literalValues is required.`);
         }
         if (series.literalValues?.some(value => !Number.isFinite(value))) {
             throw new errors_1.ChartOptionsError(`chartEx.series[${i}].literalValues must contain only finite numbers.`);

package/dist/cjs/modules/excel/chart/chart-ex-renderer.js

@@ -3561,11 +3561,8 @@ function consolidateDataForRender(space) {
 function renderChartData(data) {
     const parts = [];
     parts.push("  <cx:chartData>");
-    // NOTE: `cx:externalData` used to be emitted here, but it is a
-    // child of `cx:chartSpace` (not `cx:chartData`) per the Chart2014
-    // schema. The writer now emits it at the chartSpace level; the
-    // deprecated `data.externalData` slot is ignored here so a
-    // legacy round-trip cannot double-emit it.
+    // `cx:externalData` is a child of `cx:chartSpace`, not `cx:chartData`,
+    // per the Chart2014 schema — emitted by the chartSpace renderer.
     for (const entry of data.data) {
         parts.push(renderDataEntry(entry));
     }
@@ -3781,10 +3778,8 @@ function renderChart(chart) {
     if (chart.legend) {
         parts.push(renderLegend(chart.legend));
     }
-    // CT_Chart does NOT carry `spPr` in the ECMA-376 / Chart2014 schema
-    // — chart-frame styling lives on `CT_ChartSpace`. `chart.spPr` is a
-    // legacy type field kept for backward compat (see the @deprecated
-    // note on `ChartExChart.spPr`); do not emit it to avoid invalid XML.
+    // `CT_Chart` carries no `spPr` per the Chart2014 schema — chart-frame
+    // styling lives on `CT_ChartSpace`, emitted by the chartSpace renderer.
     if (chart.extLst) {
         parts.push(`    ${chart.extLst}`);
     }