@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/types/modules/excel/xlsx/xform/comment/threaded-comments-xform.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Reader/writer for Office 365 "threaded comments" (`<ThreadedComments>`
+ * XML root) and the workbook-level person directory (`<personList>`).
+ *
+ * Threaded comments live in a separate part tree from classic VML
+ * comments:
+ *
+ *   - `xl/threadedComments/threadedComment{N}.xml` — one per sheet
+ *     that has threaded comments; referenced from the sheet rels
+ *   - `xl/persons/person.xml` — workbook-level person directory;
+ *     referenced from the workbook rels
+ *
+ * The schema lives in Microsoft's extension namespace
+ * `http://schemas.microsoft.com/office/spreadsheetml/2018/threadedcomments`
+ * (for comments) and the older `…/2018/threadedcomments` for persons
+ * (identical URI tag-shared).
+ *
+ * This module is intentionally free of runtime xform plumbing —
+ * threaded comments are a discrete part with only text content, so
+ * two small render/parse functions suffice and plug directly into
+ * `xlsx.browser.ts` and `workbook.browser.ts`.
+ */
+import type { ThreadedComment, ThreadedCommentPerson } from "../../../types.js";
+/**
+ * Render the threaded-comment part for a single worksheet.
+ *
+ * Input is a list of `(cellRef, comment)` pairs — the cell ref is
+ * stored as the `ref` attribute on each `<threadedComment>`, not on
+ * the public {@link ThreadedComment} type (which doesn't carry it so
+ * the same structure can be shared between the public API and the
+ * XForm).
+ *
+ * Input order is preserved — Excel relies on parent-child ordering
+ * when rendering conversation threads, so callers must keep replies
+ * after their parents.
+ */
+export declare function renderThreadedComments(entries: Array<{
+    ref: string;
+    comment: ThreadedComment;
+}>): string;
+/**
+ * Parse a `xl/threadedComments/threadedComment{N}.xml` payload into
+ * structured per-cell entries. Returns an empty array on malformed
+ * input — the caller can silently drop threaded comments rather than
+ * failing the entire workbook load.
+ */
+export declare function parseThreadedComments(rawXml: string): Array<{
+    ref: string;
+    comment: ThreadedComment;
+}>;
+/**
+ * Render the workbook-level `xl/persons/person.xml` part.
+ */
+export declare function renderPersonList(persons: ThreadedCommentPerson[]): string;
+/**
+ * Parse `xl/persons/person.xml` into a {@link ThreadedCommentPerson}
+ * list. Missing ids are auto-generated so downstream parts that
+ * reference the list don't accidentally collide.
+ */
+export declare function parsePersonList(rawXml: string): ThreadedCommentPerson[];

package/dist/types/modules/excel/xlsx/xform/drawing/drawing-xform.d.ts

@@ -7,6 +7,14 @@ declare class DrawingXform extends BaseXform<DrawingModel> {
         [key: string]: any;
     };
     parser: any;
+    private _inAlternateContent;
+    private _acDepth;
+    private _inChoice;
+    private _inFallback;
+    private _fallbackDepth;
+    private _choiceRequires;
+    /** Number of anchors before entering mc:AlternateContent — used to tag new anchors */
+    private _anchorCountBeforeAC;
     constructor();
     prepare(model: DrawingModel): void;
     get tag(): string;
@@ -19,5 +27,27 @@ declare class DrawingXform extends BaseXform<DrawingModel> {
         "xmlns:xdr": string;
         "xmlns:a": string;
     };
+    /**
+     * Extended namespace set used when the drawing contains anchors
+     * wrapped in `<mc:AlternateContent>` — the ChartEx case. Excel's
+     * strict loader requires the `mc`, `r`, `c`, and `cx` prefixes at
+     * the root of `<xdr:wsDr>` before it will parse `<mc:Choice>` /
+     * `<cx:chart>` descendants. Declaring them only inside the inner
+     * `<mc:AlternateContent>` element (as earlier versions did) made
+     * Excel reject the drawing and report "Removed Part:
+     * /xl/drawings/drawingN.xml (Drawing shape)".
+     *
+     * Mirrors what Excel itself emits when it writes a drawing that
+     * hosts a ChartEx chart — see `__tests__/data/workbook-roundtrip-
+     * chartex.xlsx` (fixtures authored by Excel 2016+).
+     */
+    static DRAWING_ATTRIBUTES_WITH_MC: {
+        "xmlns:xdr": string;
+        "xmlns:a": string;
+        "xmlns:r": string;
+        "xmlns:c": string;
+        "xmlns:mc": string;
+        "xmlns:cx": string;
+    };
 }
 export { DrawingXform };

package/dist/types/modules/excel/xlsx/xform/drawing/graphic-frame-xform.d.ts

@@ -0,0 +1,54 @@
+/**
+ * GraphicFrameXform — handles `xdr:graphicFrame` elements in drawing XML.
+ *
+ * A graphicFrame is the container for embedded objects such as charts.
+ * The OOXML structure:
+ *
+ *   <xdr:graphicFrame macro="">
+ *     <xdr:nvGraphicFramePr>
+ *       <xdr:cNvPr id="2" name="Chart 1"/>
+ *       <xdr:cNvGraphicFramePr/>
+ *     </xdr:nvGraphicFramePr>
+ *     <xdr:xfrm>
+ *       <a:off x="0" y="0"/>
+ *       <a:ext cx="0" cy="0"/>
+ *     </xdr:xfrm>
+ *     <a:graphic>
+ *       <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/chart">
+ *         <c:chart xmlns:c="..." xmlns:r="..." r:id="rId1"/>
+ *       </a:graphicData>
+ *     </a:graphic>
+ *   </xdr:graphicFrame>
+ */
+import { BaseXform } from "../base-xform.js";
+export interface GraphicFrameModel {
+    /** Drawing object index (1-based unique id within the drawing part) */
+    index?: number;
+    /** Display name (e.g. "Chart 1") */
+    name?: string;
+    /** Relationship ID referencing the chart part */
+    rId?: string;
+    /** The graphic data URI — defaults to chart URI */
+    graphicDataUri?: string;
+    /** Raw XML for a:extLst inside xdr:cNvPr (round-trip preservation) */
+    cNvPrExtLst?: string;
+    /** True when the graphic frame references a cx:chart (Office 2016+ extended chart) */
+    isChartEx?: boolean;
+}
+declare class GraphicFrameXform extends BaseXform {
+    model: GraphicFrameModel;
+    parser: any;
+    private _inNvPr;
+    private _inGraphicData;
+    /** Raw XML capture for a:extLst inside xdr:cNvPr */
+    private _extLstCapture;
+    get tag(): string;
+    prepare(model: GraphicFrameModel, options: {
+        index: number;
+    }): void;
+    render(xmlStream: any, model: GraphicFrameModel): void;
+    parseOpen(node: any): boolean;
+    parseText(text: string): void;
+    parseClose(name: string): boolean;
+}
+export { GraphicFrameXform };

package/dist/types/modules/excel/xlsx/xform/drawing/one-cell-anchor-xform.d.ts

@@ -5,7 +5,9 @@ interface OneCellModel {
         tl: any;
         ext: any;
     };
-    picture: any;
+    picture?: any;
+    /** Graphic frame model (for charts and other embedded objects) */
+    graphicFrame?: any;
 }
 declare class OneCellAnchorXform extends BaseCellAnchorXform {
     constructor();

package/dist/types/modules/excel/xlsx/xform/drawing/two-cell-anchor-xform.d.ts

@@ -7,18 +7,64 @@ interface TwoCellModel {
     };
     picture?: any;
     shape?: any;
+    /** Graphic frame model (for charts and other embedded objects) */
+    graphicFrame?: any;
     /** Wrap the anchor in mc:AlternateContent for modern drawing clients */
     alternateContent?: {
         requires: string;
     };
 }
 declare class TwoCellAnchorXform extends BaseCellAnchorXform {
+    private _acDepth;
+    private _inFallback;
+    private _fallbackDepth;
+    private _choiceRequires;
     constructor();
     get tag(): string;
     prepare(model: TwoCellModel, options: {
         index: number;
     }): void;
     render(xmlStream: any, model: TwoCellModel): void;
+    /**
+     * Emit the ChartEx `<mc:AlternateContent>` block that occupies the
+     * shape slot inside a `<xdr:twoCellAnchor>` — between `<xdr:to>`
+     * and `<xdr:clientData>`.
+     *
+     * Structure mirrors Microsoft Excel's own output:
+     *
+     *   <mc:AlternateContent>
+     *     <mc:Choice Requires="cx1" xmlns:cx1="…/2015/9/8/chartex">
+     *       <xdr:graphicFrame>…<cx:chart/>…</xdr:graphicFrame>
+     *     </mc:Choice>
+     *     <mc:Fallback>
+     *       <xdr:sp>…placeholder shape…</xdr:sp>
+     *     </mc:Fallback>
+     *   </mc:AlternateContent>
+     *
+     * Both the Choice graphicFrame and the Fallback shape inherit
+     * sizing from the outer `<xdr:from>`/`<xdr:to>` cell range — they
+     * do NOT each re-declare the anchor; there is only one anchor.
+     */
+    private renderChartExAlternateContent;
+    /**
+     * Emit the placeholder `<xdr:sp>` that lives inside the
+     * `<mc:Fallback>` of a ChartEx anchor. Legacy Excel (2010/2013)
+     * and non-Microsoft loaders that don't understand the `cx1`
+     * namespace render this in place of the `cx:chart`.
+     *
+     * Matches Microsoft Excel's convention: cNvPr id=0 / empty name
+     * (a deliberate placeholder, not a real drawing object), a white
+     * rectangle sized to the anchor's cell range, and the localizable
+     * "This chart isn't available" message. The shape's own xfrm
+     * carries concrete EMU values rather than zeros because the
+     * Fallback expansion is meant to be rendered standalone — a
+     * zero-size shape would collapse and Excel 2016+ flags that as
+     * "drawing shape" validation failure even though the outer
+     * twoCellAnchor provides sizing.
+     */
+    private renderChartExFallbackShape;
+    parseOpen(node: any): boolean;
+    parseText(text: string): void;
     parseClose(name: string): boolean;
     reconcile(model: any, options: any): void;
 }

package/dist/types/modules/excel/xlsx/xform/pivot-table/pivot-table-xform.d.ts

@@ -1,4 +1,4 @@
-import type { CacheField, DataField, PivotTableSubtotal } from "../../../pivot-table.js";
+import type { CacheField, DataField, PivotTableChartFormat, PivotTableSubtotal } from "../../../pivot-table.js";
 import { BaseXform } from "../base-xform.js";
 import type { XmlSink } from "../../../../xml/types.js";
 /**
@@ -16,6 +16,17 @@ interface PivotTableRenderModel {
     cacheId: string | number;
     tableNumber: number;
     applyWidthHeightFormats: "0" | "1";
+    /**
+     * Optional top-left anchor (e.g. `"A3"`) for the pivot's displayed block.
+     * When set, the rendered `<location>` ref is computed from this anchor
+     * instead of the default `A{3 + pageOffset}`. The anchor represents the
+     * pivot's display origin — page filters (if any) occupy rows downward from
+     * the anchor, followed by a blank separator row and then the pivot body.
+     */
+    ref?: string;
+    name?: string;
+    chartFormat?: number;
+    chartFormats?: PivotTableChartFormat[];
 }
 /**
  * A single <item> element inside a pivotField's <items> collection.
@@ -151,7 +162,7 @@ interface RowColItem {
 /**
  * Chart format item for pivot charts
  */
-interface ChartFormatItem {
+interface ChartFormatItem extends PivotTableChartFormat {
     chart: number;
     format: number;
     series?: boolean;

package/dist/types/modules/excel/xlsx/xform/sheet/chartsheet-xform.d.ts

@@ -0,0 +1,185 @@
+/**
+ * ChartsheetXform — parse and render OOXML chartsheet XML.
+ *
+ * A chartsheet is a simple sheet type that contains only a chart.
+ * Structure (ECMA-376 `CT_Chartsheet`):
+ * ```xml
+ * <chartsheet xmlns="...">
+ *   <sheetPr/>?
+ *   <sheetViews><sheetView .../></sheetViews>
+ *   <sheetProtection/>?
+ *   <customSheetViews/>?
+ *   <pageMargins .../>?
+ *   <pageSetup .../>?        CT_CsPageSetup — NOT CT_PageSetup
+ *   <headerFooter/>?
+ *   <drawing r:id="rId1"/>
+ *   <legacyDrawing/>?  legacyDrawingHF?  drawingHF?  picture?  webPublishItems?  extLst?
+ * </chartsheet>
+ * ```
+ *
+ * Note that chartsheets do NOT support `printOptions`, `pageBreaks`,
+ * `rowBreaks`, or `colBreaks` — those are worksheet-only elements
+ * per ECMA-376 `CT_Chartsheet`. Likewise `<c:pageSetup>` on a
+ * chartsheet is `CT_CsPageSetup`, which has a reduced attribute set
+ * compared to the worksheet's `CT_PageSetup` (no `scale`,
+ * `fitToWidth`, `fitToHeight`, `pageOrder`, `cellComments`, or
+ * `errors`).
+ */
+import { BaseXform } from "../base-xform.js";
+import type { XmlSink } from "../../../../xml/types.js";
+export interface ChartsheetModel {
+    /** Sheet number (positional index in the XLSX archive) */
+    sheetNo: number;
+    /** Sheet name (from workbook.xml) */
+    name: string;
+    /** Sheet ID (from workbook.xml) */
+    id: number;
+    /**
+     * Tab order index — the 0-based position in the workbook's
+     * `<sheets>` list, shared between worksheets and chartsheets so a
+     * combined sort preserves the author's interleaved layout. Assigned
+     * at add time (monotonic across both add paths) and at load time
+     * (from the workbook.xml `<sheet>` ordinal).
+     */
+    orderNo?: number;
+    /** Relationship ID linking to this chartsheet from workbook.xml.rels */
+    rId?: string;
+    /** Sheet visibility state */
+    state?: "visible" | "hidden" | "veryHidden";
+    /** Tab selected */
+    tabSelected?: boolean;
+    /** Zoom scale */
+    zoomScale?: number;
+    /**
+     * `CT_ChartsheetViewBase/@workbookViewId` — 0-based index into the
+     * workbook's `<bookViews>` list that this chartsheet view is bound
+     * to. Defaults to 0 per OOXML schema; round-tripped verbatim so
+     * multi-view workbooks don't get their view hierarchy rewritten.
+     */
+    workbookViewId?: number;
+    /**
+     * `CT_ChartsheetViewBase/@zoomToFit` — when true the chartsheet
+     * scales its content to fill the window. Schema default is false;
+     * captured/written only when explicitly set to preserve round-trip.
+     */
+    zoomToFit?: boolean;
+    /** Page margins */
+    pageMargins?: {
+        l?: number;
+        r?: number;
+        t?: number;
+        b?: number;
+        left?: number;
+        right?: number;
+        top?: number;
+        bottom?: number;
+        header?: number;
+        footer?: number;
+    };
+    /**
+     * Chartsheet page setup — `CT_CsPageSetup`.
+     *
+     * Note the attribute set differs from the worksheet `CT_PageSetup`:
+     *   - **Supported**: paperSize, firstPageNumber, orientation,
+     *     usePrinterDefaults, blackAndWhite, draft, useFirstPageNumber,
+     *     horizontalDpi, verticalDpi, copies, paperHeight, paperWidth
+     *   - **Not supported on chartsheets** (worksheet-only, will be
+     *     silently ignored on write): scale, fitToWidth, fitToHeight,
+     *     pageOrder, cellComments, errors
+     */
+    pageSetup?: {
+        paperSize?: number;
+        firstPageNumber?: number;
+        orientation?: "default" | "portrait" | "landscape";
+        usePrinterDefaults?: boolean;
+        blackAndWhite?: boolean;
+        draft?: boolean;
+        useFirstPageNumber?: boolean;
+        horizontalDpi?: number;
+        verticalDpi?: number;
+        copies?: number;
+        /** Paper height in a unit-of-measure string (e.g. "11in", "297mm"). */
+        paperHeight?: string;
+        /** Paper width in a unit-of-measure string (e.g. "8.5in", "210mm"). */
+        paperWidth?: string;
+        /**
+         * Relationship id referencing a `printerSettings` part. Preserved
+         * verbatim through round-trip so an already-authored
+         * `xl/printerSettings/…` rel target keeps its XML reference from
+         * the chartsheet. Previously this attribute was dropped by the
+         * parser and never emitted by the writer, leaving the printer-
+         * settings part accessible via the chartsheet's `.rels` but
+         * unreferenced from the chartsheet XML — a dangling-rel-reverse
+         * that strict validators flag.
+         */
+        rId?: string;
+    };
+    /** Drawing relationship reference */
+    drawing?: {
+        rId: string;
+    };
+    /** Relationships parsed from the chartsheet .rels file */
+    relationships?: any[];
+    /** Drawing part name without extension (e.g. drawing2) */
+    drawingName?: string;
+    /** Classic chart number displayed by this chartsheet */
+    chartNumber?: number;
+    /** ChartEx number displayed by this chartsheet */
+    chartExNumber?: number;
+    /**
+     * Raw XML captured for elements the structured parser doesn't model
+     * (`sheetPr`, `sheetProtection`, `customSheetViews`, `headerFooter`,
+     * `legacyDrawing`, `legacyDrawingHF`, `drawingHF`, `picture`,
+     * `webPublishItems`, `extLst`). The writer emits these verbatim at
+     * the correct schema position so a round-trip through a workbook
+     * that uses chartsheet-specific features (e.g. password-protected
+     * chartsheets, printer-defined header/footer blocks) doesn't lose
+     * them.
+     *
+     * Keys are the element local name (e.g. `"sheetPr"`); values are the
+     * full `<tag …>…</tag>` serialised bytes.
+     *
+     * Note: `rowBreaks`, `colBreaks`, and `pageBreaks` are NOT captured —
+     * per ECMA-376 `CT_Chartsheet` they are worksheet-only elements.
+     * Similarly `printOptions` is worksheet-only. Legacy on-disk
+     * chartsheets that erroneously contained them are silently
+     * discarded on load to produce schema-valid output on save.
+     */
+    rawChildren?: Record<string, string>;
+}
+declare class ChartsheetXform extends BaseXform<ChartsheetModel> {
+    private inSheetView;
+    /**
+     * Raw-capture state for elements the structured parser doesn't model.
+     * When `parseOpen` sees one of the names in {@link RAW_CAPTURE_TAGS}
+     * at depth-1 of `<chartsheet>`, it starts recording the full
+     * serialised XML (open tags, text, nested children, close tags) into
+     * `captureParts`. The recording ends when `parseClose` fires with
+     * the matching root name; the assembled string is stored under
+     * `model.rawChildren[rootName]` for verbatim re-emission by
+     * {@link render}.
+     *
+     * Without this, elements like `<sheetProtection>` (password-protected
+     * chartsheets) and `<headerFooter>` silently disappeared on
+     * round-trip, breaking the author's layout / security configuration.
+     *
+     * `sheetDepth` tracks nesting depth inside `<chartsheet>`: the root
+     * itself sits at depth 1, its direct children at depth 2. Capture
+     * only ever starts at depth 2 so a nested element whose local name
+     * happens to overlap with one in {@link RAW_CAPTURE_TAGS} (e.g. an
+     * `<extLst>` inside `<customSheetViews>` as a leaf of that subtree)
+     * stays part of the outer capture rather than being promoted to a
+     * sibling root child.
+     */
+    private captureRoot;
+    private captureDepth;
+    private captureParts;
+    private skipNextCaptureClose;
+    private sheetDepth;
+    get tag(): string;
+    render(xmlStream: XmlSink, model?: ChartsheetModel): void;
+    parseOpen(node: any): boolean;
+    parseText(text: string): void;
+    parseClose(name: string): boolean;
+}
+export { ChartsheetXform };

package/dist/types/modules/excel/xlsx/xform/sheet/ext-lst-xform.d.ts

@@ -5,6 +5,7 @@ declare class ExtLstXform extends CompositeXform {
     };
     model: any;
     private ext;
+    private sparklineExt;
     constructor();
     get tag(): string;
     prepare(model: any, _options?: any): void;

package/dist/types/modules/excel/xlsx/xform/xsd-values.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared parsers for OOXML / XSD-typed attribute values.
+ *
+ * These helpers are the single source of truth for attribute parsing
+ * across every xform. Multiple xforms used to carry private copies
+ * that drifted on edge cases:
+ *   - chartsheet-xform read `tabSelected="true"` as `false` because it
+ *     only accepted `"1"` (spec permits `"true"` per `xsd:boolean`);
+ *   - some older code accepted `NaN` from `parseFloat` and serialised
+ *     it back as the literal `"NaN"` attribute — an XML Schema
+ *     violation that Excel's strict reader rejects.
+ *
+ * All parsers return `undefined` for missing / unparseable input so
+ * callers distinguish "absent" from "present but invalid" and can
+ * pipe through `?? default` to apply the spec's default value at the
+ * call site (element-specific, so the parser shouldn't bake one in).
+ */
+/**
+ * Parse an OOXML boolean attribute (`xsd:boolean`).
+ *
+ * Accepts the four canonical forms — `"1"`, `"0"`, `"true"`, `"false"` —
+ * per the XSD 1.1 spec. Leading / trailing whitespace is stripped
+ * first because XML 1.0 §3.3.3 attribute-value normalisation isn't
+ * guaranteed by every parser, and third-party writers legitimately
+ * emit `" 1 "` / `"0\n"` / etc. Without the trim, those values would
+ * silently downgrade to the schema default (typically `false`),
+ * losing state on round-trip.
+ *
+ * Returns `undefined` for any other value so call sites can
+ * distinguish "attribute absent / unrecognised" from "explicit false"
+ * and apply the element's schema default via `?? true` / `?? false`.
+ */
+export declare function parseXsdBoolean(value: string | undefined): boolean | undefined;
+/**
+ * Parse an OOXML integer attribute (`xsd:int`, bounded at ±2^31-1 per
+ * ECMA-376 / W3C XSD).
+ *
+ * Rejects trailing garbage — `parseInt("100%", 10)` silently returns
+ * `100`, which round-trips back to the wire as a valid-looking
+ * attribute even though the source was corrupt. Gate on a strict
+ * regex so only the lexical space defined by XSD is accepted; the
+ * surrounding trim handles the same third-party-writer whitespace
+ * cases {@link parseXsdBoolean} does.
+ *
+ * Returns `undefined` for missing / empty / non-numeric input rather
+ * than producing `NaN` (which would propagate through the model and
+ * surface as `"NaN"` in the round-trip XML — rejected by strict
+ * readers). Values outside `xsd:int` range are also rejected; callers
+ * that genuinely need 64-bit integers should use a `BigInt` path.
+ */
+export declare function parseXsdInt(value: string | undefined): number | undefined;
+/**
+ * Parse an OOXML floating-point attribute (`xsd:double` / `xsd:float`).
+ * See {@link parseXsdInt} for the rationale — returns `undefined`
+ * instead of `NaN` / `Infinity` so the value never escapes back into
+ * the wire as a schema-invalid attribute.
+ *
+ * Strict lexical-space regex matches `xsd:double` production:
+ * optional sign, integer / decimal, optional exponent. Rejects
+ * trailing garbage for the same reason as {@link parseXsdInt}
+ * (corrupt-source preservation is worse than loud rejection).
+ */
+export declare function parseXsdFloat(value: string | undefined): number | undefined;