@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/browser/modules/excel/xlsx/xlsx.browser.d.ts

@@ -10,7 +10,7 @@
  */
 import type { ZipTimestampMode } from "../../archive/zip-spec/timestamps.js";
 import type { PivotTableSubtotal } from "../pivot-table.js";
-import type { Workbook } from "../workbook.js";
+import type { Workbook } from "../workbook.browser.js";
 import { type IEventEmitter } from "../../stream/index.js";
 type StreamListener = Parameters<IEventEmitter["on"]>[1];
 interface EmitterLike {
@@ -101,6 +101,7 @@ export interface ZipWriterOptions {
     /** Timestamp writing strategy for ZIP entry metadata (optional). */
     timestamps?: ZipTimestampMode;
 }
+export type XlsxTemplateMode = "preserve" | "strict";
 /**
  * Options for writing an XLSX workbook.
  *
@@ -124,6 +125,54 @@ export interface XlsxWriteOptions {
      * compatibility with minimal readers.
      */
     useStyles?: boolean;
+    /**
+     * Template fidelity strategy for loaded workbooks. The default `"preserve"`
+     * byte-preserves clean chart parts and may structurally re-render edited parts
+     * when no safe raw XML patch is available. `"strict"` fails the write instead
+     * of re-rendering any edited loaded chart/chartEx part that cannot be patched
+     * in-place, preventing silent loss of unknown template XML.
+     *
+     * When a strict write fails, the thrown error enumerates the unrecognised
+     * `c15:`/`cx14:` extension paths the parser observed, so authors can decide
+     * between relaxing the mode or reshaping the mutation into a patch-friendly
+     * path. To inspect those paths *before* writing (for example to decide
+     * whether to opt into strict mode at all), use {@link Chart.unknownElements}
+     * on each chart of interest.
+     */
+    templateMode?: XlsxTemplateMode;
+    /**
+     * Convenience alias for `templateMode: "strict"`. Strict mode refuses to
+     * silently drop vendor-extension XML (`c15:…`, `cx14:…`) that the
+     * structured parser does not understand. Use this when round-tripping
+     * Excel-authored template files where preserving exotic extension
+     * elements matters more than the ability to re-render modified charts.
+     */
+    strictTemplateMode?: boolean;
+    /**
+     * Run the OOXML self-check on the produced bytes and `console.warn`
+     * every detected problem. Only {@link XLSX.writeBuffer} honours this
+     * flag — `write(stream)` / `writeFile` cannot post-validate because
+     * their output is streamed to the caller.
+     *
+     * Default resolution:
+     *   - In Node.js with `NODE_ENV !== "production"` and NOT running
+     *     under vitest (`process.env.VITEST !== "true"`): `true`.
+     *   - In production, in the browser, or under vitest: `false`.
+     *
+     * The vitest carve-out exists because running validation on every
+     * `writeBuffer` call inflates fixture `beforeAll` hooks that build
+     * hundreds of workbooks by ~50 seconds on typical hardware. Tests
+     * that want validation use {@link expectValidXlsx} directly.
+     *
+     * Pass `true` to force validation (even in production or under
+     * vitest), or `false` to suppress it (even in development). The
+     * self-check never throws: a failed validation becomes a warning so
+     * writers that intentionally produce non-conformant xlsx for
+     * testing keep working.
+     *
+     * @see OoxmlValidationReport
+     */
+    validate?: boolean;
     /**
      * Forward-compatibility / subclass extension escape hatch. Unknown keys are
      * passed through to internal writers; unrecognised keys are ignored.
@@ -176,6 +225,19 @@ declare class XLSX {
         SheetMetadata: string;
         ExternalLink: string;
         ExternalLinkPath: string;
+        Chart: string;
+        ChartEx: string;
+        ChartStyle: string;
+        ChartColors: string;
+        Drawing: string;
+        ChartUserShapes: string;
+        Chartsheet: string;
+        ThreadedComments: string;
+        Person: string;
+        Slicer: string;
+        SlicerCache: string;
+        Timeline: string;
+        TimelineCache: string;
     };
     constructor(workbook: Workbook);
     /**
@@ -204,6 +266,22 @@ declare class XLSX {
      * Shared by both Node.js write() and browser writeBuffer()
      */
     protected writeToZip(zip: IZipWriter, options?: XlsxWriteOptions): Promise<void>;
+    /**
+     * Emit the raw slicer/timeline parts captured on load. Pure
+     * byte-copy — excelts does not modify these parts. The partner
+     * Content-Types and rels are covered separately (content types in
+     * `addContentTypes`, sheet/workbook rels by the corresponding
+     * xforms consuming the existing `xl/_rels/*.rels` captured on
+     * load).
+     */
+    addSlicerAndTimelineParts(zip: IZipWriter, model: any): Promise<void>;
+    /**
+     * Write the workbook-level `xl/persons/person.xml` part when the
+     * model carries Office 365 threaded-comment authors. No-op when the
+     * persons list is empty so legacy files without threaded comments
+     * stay byte-identical.
+     */
+    addPersons(zip: IZipWriter, model: any): Promise<void>;
     /**
      * Read workbook from a stream
      */
@@ -245,15 +323,6 @@ declare class XLSX {
      * Reusable helper for passthrough and drawing processing.
      */
     protected collectStreamData(stream: IParseStream): Promise<Uint8Array>;
-    /**
-     * Check if a drawing has chart references in its relationships
-     */
-    private drawingHasChartReference;
-    /**
-     * Check if a drawing rels list references charts.
-     * Used to decide whether we need to keep raw drawing XML for passthrough.
-     */
-    private drawingRelsHasChartReference;
     /**
      * Process a known OOXML entry (workbook, styles, shared strings, etc.)
      * Returns true if handled, false if should be passed to _processDefaultEntry
@@ -277,6 +346,20 @@ declare class XLSX {
     parseWorkbook(stream: IParseStream): Promise<any>;
     parseSharedStrings(stream: IParseStream): Promise<any>;
     reconcile(model: any, options?: XlsxOptions): void;
+    /**
+     * Copy the raw bytes of each chart's user-shapes drawing part onto
+     * the owning `ChartEntry.userShapesXml` so the writer can emit them
+     * back verbatim (and so {@link Chart.userShapesXml} can surface them
+     * to user code). Runs after all ZIP entries have been processed
+     * because chart rels and drawing bytes stream in independent order.
+     *
+     * Skips charts that have no `ChartUserShapes` rel. The bytes stay
+     * keyed by drawing name (e.g. `drawing3`) inside `model.drawingRaw`
+     * since a workbook may have many user-shape drawings across
+     * different charts; we look up each chart's target through its
+     * rels file.
+     */
+    protected _reconcileChartUserShapes(model: any): void;
     /**
      * Join the three on-disk sources that together describe external workbook
      * references into a single dense `model.externalLinks: ExternalLinkModel[]`.
@@ -338,6 +421,7 @@ declare class XLSX {
         subtotal?: string;
     }>, defaultMetric: PivotTableSubtotal): PivotTableSubtotal[];
     _processWorksheetEntry(stream: IParseStream, model: any, sheetNo: number, options: XlsxOptions | undefined, path: string): Promise<void>;
+    _processChartsheetEntry(stream: IParseStream, model: any, sheetNo: number): Promise<void>;
     _processCommentEntry(stream: IParseStream, model: any, zipPath: string): Promise<void>;
     _processTableEntry(stream: IParseStream, model: any, zipPath: string): Promise<void>;
     _processWorksheetRelsEntry(stream: IParseStream, model: any, sheetNo: number): Promise<void>;
@@ -351,6 +435,15 @@ declare class XLSX {
      * @param rawData - Pre-read raw data (used in loadFromFiles path to avoid re-reading stream)
      */
     _processDrawingEntry(stream: IParseStream, model: any, name: string, rawData?: Uint8Array): Promise<void>;
+    /**
+     * Stash raw bytes of a chart-overlay drawing part. `c:userShapes`
+     * parts live under `xl/drawings/chartUserShape{N}.xml` in files we
+     * write ourselves and can use arbitrary names in foreign files (the
+     * rel target is the only authoritative reference). The bytes are
+     * keyed by the stem so `_reconcileChartUserShapes` can match them
+     * against each chart's `ChartUserShapes` rel Target.
+     */
+    _processChartUserShapesEntry(_stream: IParseStream, model: any, name: string, rawData?: Uint8Array): Promise<void>;
     _processDrawingRelsEntry(entry: any, model: any, name: string): Promise<void>;
     _processVmlDrawingEntry(entry: any, model: any, zipPath: string): Promise<void>;
     _processVmlDrawingHFEntry(entry: any, model: any, _name: string): Promise<void>;
@@ -373,17 +466,16 @@ declare class XLSX {
      * paths like `"测试.xlsx"`).
      */
     _processExternalLinkRelsEntry(stream: IParseStream, model: any, index: number): Promise<void>;
+    _processChartEntry(stream: IParseStream, model: any, chartNumber: number, rawData?: Uint8Array): Promise<void>;
+    _processChartRelsEntry(stream: IParseStream, model: any, chartNumber: number): Promise<void>;
+    _processChartStyleEntry(stream: IParseStream, model: any, styleNumber: number): Promise<void>;
+    _processChartColorsEntry(stream: IParseStream, model: any, colorsNumber: number): Promise<void>;
     loadFromFiles(zipData: Record<string, Uint8Array>, options?: XlsxReadOptions): Promise<Workbook>;
     /**
      * Process default entries (drawings, comments, tables, etc.)
      * @param rawData Optional raw entry data for passthrough preservation (used by loadFromFiles)
      */
     protected _processDefaultEntry(stream: IParseStream, model: any, entryName: string, rawData?: Uint8Array): Promise<boolean>;
-    /**
-     * Store a passthrough file for preservation during read/write cycles.
-     * These files are not parsed but stored as raw bytes to be written back unchanged.
-     */
-    _processPassthroughEntry(stream: IParseStream, model: any, entryName: string): Promise<void>;
     /**
      * Helper: render an xform directly to a streaming zip entry.
      * Avoids buffering the entire XML string in memory.
@@ -402,7 +494,12 @@ declare class XLSX {
     addStyles(zip: IZipWriter, model: any): Promise<void>;
     addWorkbook(zip: IZipWriter, model: any): Promise<void>;
     addWorksheets(zip: IZipWriter, model: any): Promise<void>;
+    addChartsheets(zip: IZipWriter, model: any): Promise<void>;
     addDrawings(zip: IZipWriter, model: any): Promise<void>;
+    addCharts(zip: IZipWriter, model: any, strictTemplateMode?: boolean): Promise<void>;
+    addChartExEntries(zip: IZipWriter, model: any, strictTemplateMode?: boolean): Promise<void>;
+    private _appendChartExSidecars;
+    private _buildChartExRels;
     addTables(zip: IZipWriter, model: any): Promise<void>;
     /**
      * Write every external workbook reference into the archive. For each
@@ -415,16 +512,13 @@ declare class XLSX {
      * relative** `Target` whenever the user supplied one. This is the single
      * line that makes Office / WPS resolve the referenced workbook relative
      * to the current file's directory (not the `%USERPROFILE%\Documents`
-     * fallback) — the root of the behaviour reported in exceljs#3039.
+     * fallback) — the root of the relative-path external-link behaviour.
      */
     addExternalLinks(zip: IZipWriter, model: any): Promise<void>;
-    /**
-     * Write passthrough files (charts, etc.) that were preserved during read.
-     * These files are written back unchanged to preserve unsupported features.
-     */
-    addPassthrough(zip: IZipWriter, model: any): void;
     addPivotTables(zip: IZipWriter, model: any): Promise<void>;
     _finalize(zip: IZipWriter): Promise<this>;
     prepareModel(model: any, options: any): void;
+    prepareChartExSidecars(model: any): void;
+    prepareChartsheets(model: any): void;
 }
 export { XLSX };