@cj-tech-master/excelts 9.4.2 → 9.5.0

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

@@ -3,10 +3,52 @@
  *
  * Extends browser Workbook with Node.js file system support for CSV and Markdown operations.
  */
+import { type WorkbookReaderOptions, type NodeInput } from "./stream/workbook-reader.js";
+import type { WorkbookReader as WorkbookReaderBrowser } from "./stream/workbook-reader.browser.js";
+import { type WorkbookWriterOptions } from "./stream/workbook-writer.js";
+import type { WorkbookWriter as WorkbookWriterBrowser } from "./stream/workbook-writer.browser.js";
 import { Workbook as WorkbookBrowser, type CsvOptions } from "./workbook.browser.js";
 import type { Worksheet } from "./worksheet.js";
+import { XLSX } from "./xlsx/xlsx.js";
 import type { MarkdownOptions } from "../markdown/types.js";
 declare class Workbook extends WorkbookBrowser {
+    private _xlsxNode?;
+    /**
+     * xlsx file format operations — Node.js variant. Exposes the
+     * `readFile` / `writeFile` / streaming `read` / `write` methods that
+     * the browser XLSX omits. Overriding here (rather than typing the
+     * base getter as Node XLSX directly) keeps the browser
+     * `Workbook.xlsx` type clean — browser consumers see only the
+     * operations the bundle actually supports and get a TS error if
+     * they accidentally reach for file-path APIs.
+     */
+    get xlsx(): XLSX;
+    /**
+     * Create a streaming workbook writer — Node.js variant. Accepts the
+     * Node-only `{ filename }` option for direct file-path output in
+     * addition to the cross-platform `{ stream }` option. Overriding
+     * here (rather than typing the base factory as the Node writer)
+     * keeps the browser bundle free of Node-only stream code.
+     *
+     * The return type is declared as the browser `WorkbookWriter` to
+     * preserve static-side Liskov compatibility with the base class;
+     * downcast at the call site if the Node subclass API is needed, or
+     * use `new WorkbookWriter()` directly.
+     */
+    static createStreamWriter(options?: WorkbookWriterOptions): WorkbookWriterBrowser;
+    /**
+     * Create a streaming workbook reader — Node.js variant. Accepts a
+     * Node-only file-path `string` in addition to the cross-platform
+     * `CommonInput` types (buffer / readable). Overriding here keeps the
+     * browser bundle free of Node-only `fs` imports.
+     *
+     * The return type is declared as the browser `WorkbookReader` to
+     * preserve static-side Liskov compatibility with the base class.
+     * The runtime instance is the Node `WorkbookReader` subclass and
+     * handles file-path inputs transparently; downcast if the subclass
+     * API is needed, or use `new WorkbookReader()` directly.
+     */
+    static createStreamReader(input: NodeInput, options?: WorkbookReaderOptions): WorkbookReaderBrowser;
     /**
      * Read CSV from file (Node.js only)
      *
@@ -61,3 +103,4 @@ declare class Workbook extends WorkbookBrowser {
 }
 export { Workbook };
 export type { CsvOptions, CsvInput, WorkbookModel, WorkbookMedia, WorkbookProtectionModel, ExternalLinkModel, ExternalLinkCachedSheet } from "./workbook.browser.js";
+export type { AddChartsheetOptions, AddPivotChartsheetOptions, ChartsheetOptions, ChartsheetViewOptions } from "./chartsheet.js";

package/dist/browser/modules/excel/workbook.js

@@ -4,12 +4,60 @@
  * Extends browser Workbook with Node.js file system support for CSV and Markdown operations.
  */
 import { ExcelFileError } from "./errors.js";
+import { WorkbookReader } from "./stream/workbook-reader.browser.js";
+import { WorkbookWriter } from "./stream/workbook-writer.browser.js";
 import { Workbook as WorkbookBrowser } from "./workbook.browser.js";
+import { XLSX } from "./xlsx/xlsx.browser.js";
 import { fileExists, createReadStream, createWriteStream, readFileText, writeFileText } from "../../utils/fs.browser.js";
 // =============================================================================
 // Node.js Workbook Class
 // =============================================================================
 class Workbook extends WorkbookBrowser {
+    /**
+     * xlsx file format operations — Node.js variant. Exposes the
+     * `readFile` / `writeFile` / streaming `read` / `write` methods that
+     * the browser XLSX omits. Overriding here (rather than typing the
+     * base getter as Node XLSX directly) keeps the browser
+     * `Workbook.xlsx` type clean — browser consumers see only the
+     * operations the bundle actually supports and get a TS error if
+     * they accidentally reach for file-path APIs.
+     */
+    get xlsx() {
+        if (!this._xlsxNode) {
+            this._xlsxNode = new XLSX(this);
+        }
+        return this._xlsxNode;
+    }
+    /**
+     * Create a streaming workbook writer — Node.js variant. Accepts the
+     * Node-only `{ filename }` option for direct file-path output in
+     * addition to the cross-platform `{ stream }` option. Overriding
+     * here (rather than typing the base factory as the Node writer)
+     * keeps the browser bundle free of Node-only stream code.
+     *
+     * The return type is declared as the browser `WorkbookWriter` to
+     * preserve static-side Liskov compatibility with the base class;
+     * downcast at the call site if the Node subclass API is needed, or
+     * use `new WorkbookWriter()` directly.
+     */
+    static createStreamWriter(options) {
+        return new WorkbookWriter(options);
+    }
+    /**
+     * Create a streaming workbook reader — Node.js variant. Accepts a
+     * Node-only file-path `string` in addition to the cross-platform
+     * `CommonInput` types (buffer / readable). Overriding here keeps the
+     * browser bundle free of Node-only `fs` imports.
+     *
+     * The return type is declared as the browser `WorkbookReader` to
+     * preserve static-side Liskov compatibility with the base class.
+     * The runtime instance is the Node `WorkbookReader` subclass and
+     * handles file-path inputs transparently; downcast if the subclass
+     * API is needed, or use `new WorkbookReader()` directly.
+     */
+    static createStreamReader(input, options) {
+        return new WorkbookReader(input, options);
+    }
     /**
      * Read CSV from file (Node.js only)
      *

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

@@ -1,4 +1,10 @@
 import type { Cell, FormulaResult } from "./cell.js";
+import type { ChartSupport } from "./chart-host-registry.js";
+import type { Chart, ChartAnchorModel } from "./chart/chart.js";
+import type { AddChartExFromRowsOptions, AddChartExFromTableOptions, AddChartFromRowsOptions, AddChartFromTableOptions, SeriesFromColumnsOptions } from "./chart/chart-api.js";
+import type { AddChartExOptions } from "./chart/chart-ex-types.js";
+import type { ExcelChartExPreset, ExcelChartPreset } from "./chart/chart-presets.js";
+import type { AddBarChartOptions, AddChartOptions, AddChartRange, AddComboChartOptions, AddPieChartOptions, AddScatterChartOptions, AddSurfaceChartOptions } from "./chart/types.js";
 import { Column, type ColumnModel, type ColumnDefn } from "./column.js";
 import { DataValidations } from "./data-validations.js";
 import { FormCheckbox, type FormCheckboxModel, type FormCheckboxOptions, type FormControlRange } from "./form-control.js";
@@ -6,8 +12,9 @@ import { Image, type ImageModel } from "./image.js";
 import { type PivotTable, type PivotTableModel } from "./pivot-table.js";
 import { Range, type RangeInput } from "./range.js";
 import { Row, type RowModel } from "./row.js";
+import type { AddSparklineGroupOptions, SparklineGroup } from "./sparkline/index.js";
 import { Table, type TableModel } from "./table.js";
-import type { AddImageRange, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, IgnoredError, RowBreak, RowValues, TableProperties, WatermarkOptions, WorksheetProperties, WorksheetState, WorksheetView } from "./types.js";
+import type { AddImageRange, AutoFilter, CellValue, ColBreak, ConditionalFormattingOptions, DataValidation, IgnoredError, RowBreak, RowValues, TableProperties, ThreadedComment, WatermarkOptions, WorksheetProperties, WorksheetState, WorksheetView } from "./types.js";
 import { type Origin } from "./utils/address.js";
 import type { Workbook } from "./workbook.js";
 type DataValidationModel = {
@@ -116,6 +123,19 @@ interface WorksheetModel {
     mergeCells?: string[];
     /** Loaded drawing data (for charts, etc.) - preserved for round-trip */
     drawing?: unknown;
+    /** Chart anchor models for worksheet charts */
+    charts?: ChartAnchorModel[];
+    /** Sparkline groups (x14:sparklineGroups) */
+    sparklineGroups?: SparklineGroup[];
+    /**
+     * Office 365 threaded comments for this worksheet. Rendered as a
+     * separate `xl/threadedComments/threadedComment{N}.xml` part. Empty
+     * when the sheet has no modern comments.
+     */
+    threadedComments?: Array<{
+        ref: string;
+        comment: ThreadedComment;
+    }>;
 }
 declare class Worksheet {
     private _workbook;
@@ -136,6 +156,8 @@ declare class Worksheet {
     views: Partial<WorksheetView>[];
     autoFilter: AutoFilter | null;
     private _media;
+    private _charts;
+    private _sparklineGroups;
     sheetProtection: SheetProtection | null;
     tables: {
         [key: string]: Table;
@@ -144,6 +166,23 @@ declare class Worksheet {
     conditionalFormattings: ConditionalFormattingOptions[];
     formControls: FormCheckbox[];
     ignoredErrors: IgnoredError[];
+    /**
+     * Office 365 threaded comments attached to this sheet, keyed by
+     * cell reference. Each cell may carry a linear conversation (a
+     * top-level comment followed by replies whose `parentId` points at
+     * the top-level entry). Round-tripped verbatim on load; mutating
+     * the array triggers a fresh `xl/threadedComments/threadedComment{N}.xml`
+     * on save.
+     *
+     * Distinct from (and can coexist with) classic VML notes — modern
+     * Excel shows threaded comments in the conversation pane, classic
+     * VML in the tooltip. When both are present the threaded text is
+     * authoritative.
+     */
+    threadedComments: Array<{
+        ref: string;
+        comment: ThreadedComment;
+    }>;
     private _headerRowCount?;
     /** Loaded drawing data (for charts, etc.) - preserved for round-trip */
     private _drawing;
@@ -288,6 +327,13 @@ declare class Worksheet {
     mergeCellsWithoutStyle(...cells: RangeInput[]): void;
     private _mergeCellsInternal;
     private _unMergeMaster;
+    /**
+     * Shift all chart anchors (drawing anchors + programmatic charts) by delta along an axis.
+     * @param axis "row" or "col"
+     * @param threshold 0-based index; anchors at or beyond this are shifted
+     * @param delta number of positions to shift (positive = expand, negative = shrink)
+     */
+    private _shiftChartAnchors;
     /**
      * Update _merges dictionary and cell-level merge references after a row or column splice.
      */
@@ -306,6 +352,109 @@ declare class Worksheet {
      */
     addImage(imageId: string | number, range: AddImageRange): void;
     getImages(): Image[];
+    /**
+     * Add a chart to the worksheet, positioned at the given range.
+     * Returns the chart number (1-based) that identifies this chart in the workbook.
+     */
+    addChart(options: AddChartOptions, range: AddChartRange): number;
+    addColumnChart(options: Omit<AddBarChartOptions, "type" | "barDir">, range: AddChartRange): number;
+    addBarChart(options: Omit<AddBarChartOptions, "type" | "barDir">, range: AddChartRange): number;
+    addLineChart(options: Omit<AddChartOptions, "type">, range: AddChartRange): number;
+    addAreaChart(options: Omit<AddChartOptions, "type">, range: AddChartRange): number;
+    addPieChart(options: Omit<AddPieChartOptions, "type">, range: AddChartRange): number;
+    addDoughnutChart(options: Omit<AddPieChartOptions, "type">, range: AddChartRange): number;
+    addScatterChart(options: Omit<AddScatterChartOptions, "type">, range: AddChartRange): number;
+    addBubbleChart(options: Omit<AddChartOptions, "type">, range: AddChartRange): number;
+    addRadarChart(options: Omit<AddChartOptions, "type">, range: AddChartRange): number;
+    addStockChart(options: Omit<AddChartOptions, "type">, range: AddChartRange): number;
+    addSurfaceChart(options: Omit<AddSurfaceChartOptions, "type">, range: AddChartRange): number;
+    addHistogramChart(options: Omit<AddChartExOptions, "type">, range: AddChartRange): number;
+    addParetoChart(options: Omit<AddChartExOptions, "type">, range: AddChartRange): number;
+    addWaterfallChart(options: Omit<AddChartExOptions, "type">, range: AddChartRange): number;
+    addFunnelChart(options: Omit<AddChartExOptions, "type">, range: AddChartRange): number;
+    addTreemapChart(options: Omit<AddChartExOptions, "type">, range: AddChartRange): number;
+    addSunburstChart(options: Omit<AddChartExOptions, "type">, range: AddChartRange): number;
+    addBoxWhiskerChart(options: Omit<AddChartExOptions, "type">, range: AddChartRange): number;
+    addRegionMapChart(options: Omit<AddChartExOptions, "type">, range: AddChartRange): number;
+    addPresetChart(preset: ExcelChartPreset, options: Omit<AddChartOptions, "type"> & Partial<Pick<AddChartOptions, "type">>, range: AddChartRange): number;
+    addPresetChartEx(preset: ExcelChartExPreset, options: Omit<AddChartExOptions, "type"> & Partial<Pick<AddChartExOptions, "type">>, range: AddChartRange): number;
+    seriesFromColumns(options: SeriesFromColumnsOptions): ReturnType<ChartSupport["seriesFromColumns"]>;
+    addChartFromTable(table: Table | string, options: AddChartFromTableOptions, range: AddChartRange): number;
+    addChartFromRows<T extends Record<string, unknown>>(rows: T[], options: AddChartFromRowsOptions<T>, range: AddChartRange): number;
+    addColumnChartFromRows<T extends Record<string, unknown>>(rows: T[], options: Omit<AddChartFromRowsOptions<T>, "type" | "barDir">, range: AddChartRange): number;
+    /**
+     * Add a chartEx chart whose data references come from a worksheet Table.
+     * Mirrors {@link addChartFromTable} for the modern `cx:` chart types
+     * (sunburst, treemap, waterfall, funnel, histogram, pareto, boxWhisker).
+     * `regionMap` is not supported through this helper because its data
+     * model expects geographic labels — use {@link addChartEx} directly.
+     */
+    addChartExFromTable(table: Table | string, options: AddChartExFromTableOptions & {
+        type: Exclude<AddChartExOptions["type"], "regionMap">;
+    }, range: AddChartRange): number;
+    /**
+     * Add a chartEx chart whose rows come from a plain object-array, staged
+     * into the worksheet before being referenced by absolute range. Mirrors
+     * {@link addChartFromRows} for the modern `cx:` chart types.
+     */
+    addChartExFromRows<T extends Record<string, unknown>>(rows: T[], options: AddChartExFromRowsOptions<T> & {
+        type: Exclude<AddChartExOptions["type"], "regionMap">;
+    }, range: AddChartRange): number;
+    /**
+     * Add a classic pivot chart linked to an existing pivot table.
+     * Returns the chart number (1-based) that identifies this chart in the workbook.
+     */
+    addPivotChart(pivotTable: PivotTable, options: AddChartOptions, range: AddChartRange): number;
+    /**
+     * Add a combo pivot chart linked to an existing pivot table.
+     * Returns the chart number (1-based) that identifies this chart in the workbook.
+     */
+    addPivotComboChart(pivotTable: PivotTable, options: AddComboChartOptions, range: AddChartRange): number;
+    /**
+     * Add a combo chart (multiple chart type groups) to the worksheet.
+     * Returns the chart number (1-based) that identifies this chart in the workbook.
+     */
+    addComboChart(options: AddComboChartOptions, range: AddChartRange): number;
+    /**
+     * Add a ChartEx (Office 2016+ extended chart) to the worksheet.
+     *
+     * Supported types: `sunburst`, `treemap`, `waterfall`, `funnel`, `histogram`,
+     * `pareto`, `boxWhisker`, `regionMap`.
+     *
+     * Returns the chartEx number (1-based) that identifies this chart in the workbook.
+     */
+    addChartEx(options: AddChartExOptions, range: AddChartRange): number;
+    private _applyChartSidecars;
+    /**
+     * Get all charts embedded in this worksheet.
+     */
+    getCharts(): Chart[];
+    /**
+     * Remove a chart from this worksheet.
+     *
+     * @param chart - Either the chart object or its 0-based index in the worksheet.
+     * @returns `true` if a chart was removed, `false` otherwise.
+     */
+    removeChart(chart: Chart | number): boolean;
+    /**
+     * Add a sparkline group to this worksheet.
+     *
+     * A sparkline group is a collection of small in-cell charts sharing common
+     * styling. Sparklines are rendered via `x14:sparklineGroups` inside the
+     * worksheet extension list.
+     *
+     * @returns The newly added SparklineGroup for further modification.
+     */
+    addSparklineGroup(options: AddSparklineGroupOptions): SparklineGroup;
+    /** Get all sparkline groups on this worksheet. */
+    getSparklineGroups(): SparklineGroup[];
+    /**
+     * Remove a sparkline group.
+     *
+     * @param groupOrIndex - The group object or its 0-based index.
+     * @returns `true` if removed, `false` otherwise.
+     */
+    removeSparklineGroup(groupOrIndex: SparklineGroup | number): boolean;
     /**
      * Using the image id from `Workbook.addImage`, set the background to the worksheet
      */
@@ -402,9 +551,14 @@ declare class Worksheet {
      */
     addConditionalFormatting(cf: ConditionalFormattingOptions): void;
     /**
-     * Delete conditional formatting rules
+     * Delete conditional formatting rules.
+     *
+     * - When `filter` is a number, removes the rule at that index.
+     * - When `filter` is a function, removes every rule for which it returns `true`
+     *   (i.e. the predicate selects the rules to delete, not the ones to keep).
+     * - When `filter` is omitted/falsy, removes all rules.
      */
-    removeConditionalFormatting(filter: number | ((value: ConditionalFormattingOptions, index: number, array: ConditionalFormattingOptions[]) => boolean)): void;
+    removeConditionalFormatting(filter?: number | ((value: ConditionalFormattingOptions, index: number, array: ConditionalFormattingOptions[]) => boolean)): void;
     /**
      * Auto-fit a single column's width to its content.
      *