@libraz/formulon 0.15.2 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -15,7 +15,7 @@ Known differences from Excel are listed case by case in [`tests/divergence.yaml`
15
15
  ## What's inside
16
16
 
17
17
  - **Formula engine** — 526 Excel function names, 511 implemented locally; dynamic arrays, `LET` / `LAMBDA`, and `REGEX*`. [Coverage](https://formulon.libraz.net/compatibility/formula-coverage)
18
- - **Workbook I/O** — read, recalculate and write `.xlsx` and `.xlsb`, including styles, conditional formatting, tables, pivot tables and print layout. [File formats](https://formulon.libraz.net/compatibility/file-format-support)
18
+ - **Workbook I/O** — read, recalculate and write `.xlsx` and `.xlsb`, including styles, conditional formatting, tables, pivot tables, charts and print layout. [File formats](https://formulon.libraz.net/compatibility/file-format-support)
19
19
  - **Locale profiles** — 28 Excel behavior profiles across fourteen locales on Mac and Windows hosts. [Locale profiles](https://formulon.libraz.net/compatibility/locale-profiles)
20
20
  - **Excel oracle** — formula results are compared bit for bit against goldens captured from Mac Excel 365 in fourteen locales. [Oracle testing](https://formulon.libraz.net/compatibility/oracle-testing)
21
21
  - **Two builds** — a single-threaded default that loads anywhere, and `@libraz/formulon/threads` for parallel recalculation. [Choosing a build](#choosing-a-build)
package/dist/common.js CHANGED
@@ -49,6 +49,10 @@ export const PivotShowValuesAs = Object.freeze({
49
49
  PercentOfParentRow: 9,
50
50
  PercentOfParentCol: 10,
51
51
  PercentOfParent: 11,
52
+ PercentOf: 12,
53
+ PercentOfRunningTotal: 13,
54
+ RankAscending: 14,
55
+ RankDescending: 15,
52
56
  });
53
57
  export const PIVOT_SHOW_AS_BASE_PREVIOUS = 1048828;
54
58
  export const PIVOT_SHOW_AS_BASE_NEXT = 1048829;
@@ -168,6 +172,60 @@ export const DrawingObjectKind = Object.freeze({
168
172
  });
169
173
  export const AnchorKind = Object.freeze({ OneCell: 0, TwoCell: 1, Absolute: 2 });
170
174
  export const AnchorEditAs = Object.freeze({ TwoCell: 0, OneCell: 1, Absolute: 2 });
175
+ export const ChartPlotType = Object.freeze({
176
+ Bar: 0,
177
+ Bar3D: 1,
178
+ Line: 2,
179
+ Line3D: 3,
180
+ Area: 4,
181
+ Area3D: 5,
182
+ Pie: 6,
183
+ Pie3D: 7,
184
+ Doughnut: 8,
185
+ OfPie: 9,
186
+ Scatter: 10,
187
+ Bubble: 11,
188
+ Radar: 12,
189
+ Stock: 13,
190
+ Surface: 14,
191
+ Surface3D: 15,
192
+ Chartex: 16,
193
+ });
194
+ export const ChartInsertKind = Object.freeze({ Column: 0, Bar: 1, Line: 2, Area: 3, Pie: 4, Scatter: 5, Doughnut: 6 });
195
+ export const ChartGrouping = Object.freeze({ Clustered: 0, Stacked: 1, PercentStacked: 2, Standard: 3 });
196
+ export const ChartBlanksAs = Object.freeze({ Absent: 0, Gap: 1, Zero: 2, Span: 3 });
197
+ export const ChartPointState = Object.freeze({ Value: 0, Gap: 1, Connect: 2 });
198
+ export const ChartAxisKind = Object.freeze({ Category: 0, Value: 1, Date: 2, Series: 3 });
199
+ export const ChartAxisCrosses = Object.freeze({ Absent: 0, AutoZero: 1, Min: 2, Max: 3, At: 4 });
200
+ export const ChartTitleKind = Object.freeze({ None: 0, Text: 1, Ref: 2, Auto: 3 });
201
+ export const ChartSeriesDirection = Object.freeze({ Auto: 0, Columns: 1, Rows: 2 });
202
+ export const ChartLegendPosition = Object.freeze({ None: 0, Bottom: 1, Top: 2, Left: 3, Right: 4, TopRight: 5 });
203
+ export const ChartLineDash = Object.freeze({ Solid: 0, Dash: 1, Dot: 2, DashDot: 3, Other: 4 });
204
+ export const ChartMarkerSymbol = Object.freeze({
205
+ None: 0,
206
+ Auto: 1,
207
+ Circle: 2,
208
+ Square: 3,
209
+ Diamond: 4,
210
+ Triangle: 5,
211
+ X: 6,
212
+ Star: 7,
213
+ Plus: 8,
214
+ Dot: 9,
215
+ Dash: 10,
216
+ Picture: 11,
217
+ });
218
+ export const ChartLabelPosition = Object.freeze({
219
+ BestFit: 0,
220
+ Center: 1,
221
+ InsideBase: 2,
222
+ InsideEnd: 3,
223
+ OutsideEnd: 4,
224
+ Above: 5,
225
+ Below: 6,
226
+ Left: 7,
227
+ Right: 8,
228
+ });
171
229
  export const ThemeSource = Object.freeze({ Part: 0, Default: 1, Unparseable: 2 });
172
230
  export const EffectiveStyleSource = Object.freeze({ Cell: 0, Row: 1, Column: 2, Default: 3 });
173
231
  export const DisplayStatus = Object.freeze({ Ok: 0, Overflow: 1, InvalidFormat: 2 });
@@ -325,6 +325,10 @@ export enum PivotShowValuesAs {
325
325
  PercentOfParentRow = 9,
326
326
  PercentOfParentCol = 10,
327
327
  PercentOfParent = 11,
328
+ PercentOf = 12,
329
+ PercentOfRunningTotal = 13,
330
+ RankAscending = 14,
331
+ RankDescending = 15,
328
332
  }
329
333
 
330
334
  /** Sentinel value for `PivotDataFieldSpec.showAsBaseItem` meaning
@@ -794,7 +798,7 @@ export interface SheetFormatDefaultsResult extends SheetFormatDefaults {
794
798
  status: Status;
795
799
  /** Character units the sheet lays columns out with: `defaultColWidth` when set, else 8.43. */
796
800
  effectiveDefaultColWidth: number;
797
- /** Points the sheet lays rows out with: `defaultRowHeight` when set, else 102/7 (about 14.57). */
801
+ /** Points the sheet lays rows out with: `defaultRowHeight` when set, else 102/7 (about 14.57); 0 when `zeroHeight` hides rows by default. */
798
802
  effectiveDefaultRowHeight: number;
799
803
  }
800
804
 
@@ -1899,6 +1903,141 @@ export enum AnchorEditAs {
1899
1903
  Absolute = 2,
1900
1904
  }
1901
1905
 
1906
+ /** Plot group type. Mirrors `fm_chart_plot_type_t`. */
1907
+ export enum ChartPlotType {
1908
+ Bar = 0,
1909
+ Bar3D = 1,
1910
+ Line = 2,
1911
+ Line3D = 3,
1912
+ Area = 4,
1913
+ Area3D = 5,
1914
+ Pie = 6,
1915
+ Pie3D = 7,
1916
+ Doughnut = 8,
1917
+ OfPie = 9,
1918
+ Scatter = 10,
1919
+ Bubble = 11,
1920
+ Radar = 12,
1921
+ Stock = 13,
1922
+ Surface = 14,
1923
+ Surface3D = 15,
1924
+ Chartex = 16,
1925
+ }
1926
+
1927
+ /** Kinds `insertChart` and `setChartType` produce. Mirrors `fm_chart_insert_kind_t`. */
1928
+ export enum ChartInsertKind {
1929
+ Column = 0,
1930
+ Bar = 1,
1931
+ Line = 2,
1932
+ Area = 3,
1933
+ Pie = 4,
1934
+ Scatter = 5,
1935
+ Doughnut = 6,
1936
+ }
1937
+
1938
+ /** Series grouping of a column, bar, line or area plot. Mirrors `fm_chart_grouping_t`. */
1939
+ export enum ChartGrouping {
1940
+ Clustered = 0,
1941
+ Stacked = 1,
1942
+ PercentStacked = 2,
1943
+ Standard = 3,
1944
+ }
1945
+
1946
+ /** How blank cells are plotted; `Absent` writes no element. Mirrors `fm_chart_blanks_as_t`. */
1947
+ export enum ChartBlanksAs {
1948
+ Absent = 0,
1949
+ Gap = 1,
1950
+ Zero = 2,
1951
+ Span = 3,
1952
+ }
1953
+
1954
+ /** How a resolved point is drawn. Mirrors `fm_chart_point_state_t`. */
1955
+ export enum ChartPointState {
1956
+ Value = 0,
1957
+ Gap = 1,
1958
+ Connect = 2,
1959
+ }
1960
+
1961
+ /** Axis kind. Mirrors `fm_chart_axis_kind_t`. */
1962
+ export enum ChartAxisKind {
1963
+ Category = 0,
1964
+ Value = 1,
1965
+ Date = 2,
1966
+ Series = 3,
1967
+ }
1968
+
1969
+ /** Where an axis crosses its cross axis; `At` uses `crossesAt`. Mirrors `fm_chart_axis_crosses_t`. */
1970
+ export enum ChartAxisCrosses {
1971
+ Absent = 0,
1972
+ AutoZero = 1,
1973
+ Min = 2,
1974
+ Max = 3,
1975
+ At = 4,
1976
+ }
1977
+
1978
+ /** Title kind; `Auto` is a title element without text, left to the viewer. Mirrors `fm_chart_title_kind_t`. */
1979
+ export enum ChartTitleKind {
1980
+ None = 0,
1981
+ Text = 1,
1982
+ Ref = 2,
1983
+ Auto = 3,
1984
+ }
1985
+
1986
+ /** Whether series run down columns or across rows; `Auto` follows Excel. Mirrors `fm_chart_series_direction_t`. */
1987
+ export enum ChartSeriesDirection {
1988
+ Auto = 0,
1989
+ Columns = 1,
1990
+ Rows = 2,
1991
+ }
1992
+
1993
+ /** Legend position; `None` has no legend. Mirrors `fm_chart_legend_position_t`. */
1994
+ export enum ChartLegendPosition {
1995
+ None = 0,
1996
+ Bottom = 1,
1997
+ Top = 2,
1998
+ Left = 3,
1999
+ Right = 4,
2000
+ TopRight = 5,
2001
+ }
2002
+
2003
+ /** Outline dash style. Mirrors `fm_chart_line_dash_t`. */
2004
+ export enum ChartLineDash {
2005
+ Solid = 0,
2006
+ Dash = 1,
2007
+ Dot = 2,
2008
+ DashDot = 3,
2009
+ Other = 4,
2010
+ }
2011
+
2012
+ /** Marker symbol. Mirrors `fm_chart_marker_symbol_t`. `Picture` is read-only: a patch carrying it is rejected. */
2013
+ export enum ChartMarkerSymbol {
2014
+ None = 0,
2015
+ Auto = 1,
2016
+ Circle = 2,
2017
+ Square = 3,
2018
+ Diamond = 4,
2019
+ Triangle = 5,
2020
+ X = 6,
2021
+ Star = 7,
2022
+ Plus = 8,
2023
+ Dot = 9,
2024
+ Dash = 10,
2025
+ Picture = 11,
2026
+ }
2027
+
2028
+ /** Data label position. Mirrors `fm_chart_label_position_t`. */
2029
+ export enum ChartLabelPosition {
2030
+ BestFit = 0,
2031
+ Center = 1,
2032
+ InsideBase = 2,
2033
+ InsideEnd = 3,
2034
+ OutsideEnd = 4,
2035
+ Above = 5,
2036
+ Below = 6,
2037
+ Left = 7,
2038
+ Right = 8,
2039
+ }
2040
+
1902
2041
  /** How a colour was resolved. Mirrors `fm_color_resolution_t`. `Exact` is a literal or workbook-supplied
1903
2042
  * colour; `DefaultTheme` / `ThemeUnparseable` mean the current Excel Office (Aptos) theme was used because
1904
2043
  * the theme part is absent / unparseable; `IndexOutOfRange` is black; `AutoContext` is an automatic colour
@@ -2282,7 +2421,7 @@ export interface ImageInsertOptions {
2282
2421
  heightEmu?: number;
2283
2422
  }
2284
2423
 
2285
- /** Result of `Workbook.insertImage` and `Workbook.restoreImage`; `objectId` is zero on failure. */
2424
+ /** Result of `Workbook.insertImage` and `Workbook.restoreDrawing`; `objectId` is zero on failure. */
2286
2425
  export interface InsertImageResult {
2287
2426
  status: Status;
2288
2427
  objectId: number;
@@ -2304,6 +2443,322 @@ export interface ImagePlacement {
2304
2443
  heightEmu?: number;
2305
2444
  }
2306
2445
 
2446
+ /** One series input: nothing, a range reference, or literal points. */
2447
+ export interface ChartDataSource {
2448
+ kind: 'none' | 'ref' | 'literal';
2449
+ formula: string;
2450
+ literal: (number | string)[];
2451
+ }
2452
+
2453
+ /** Solid fill; `color` is ARGB (`0xAARRGGBB`), `transparency` a percentage (0..100). */
2454
+ export interface ChartFillInfo {
2455
+ color: number | null;
2456
+ transparency: number | null;
2457
+ }
2458
+
2459
+ export interface ChartLineInfo {
2460
+ color: number | null;
2461
+ transparency: number | null;
2462
+ widthPt: number | null;
2463
+ dash: ChartLineDash | null;
2464
+ none: boolean;
2465
+ }
2466
+
2467
+ export interface ChartMarkerInfo {
2468
+ symbol: ChartMarkerSymbol;
2469
+ size: number | null;
2470
+ fill: ChartFillInfo;
2471
+ line: ChartLineInfo;
2472
+ }
2473
+
2474
+ export interface ChartLabelsInfo {
2475
+ showValue: boolean;
2476
+ showCategory: boolean;
2477
+ showSeries: boolean;
2478
+ showPercent: boolean;
2479
+ showLegendKey: boolean;
2480
+ separator: string | null;
2481
+ position: ChartLabelPosition | null;
2482
+ numberFormat: string | null;
2483
+ sourceLinked: boolean;
2484
+ fontColor: number | null;
2485
+ fontSizePt: number | null;
2486
+ deleted: boolean;
2487
+ }
2488
+
2489
+ /** A formatted data point (`c:dPt`). */
2490
+ export interface ChartPointInfo {
2491
+ idx: number;
2492
+ fill: ChartFillInfo;
2493
+ line: ChartLineInfo;
2494
+ marker: ChartMarkerInfo | null;
2495
+ }
2496
+
2497
+ export interface ChartSeriesInfo {
2498
+ idx: number;
2499
+ order: number;
2500
+ filtered: boolean;
2501
+ name: ChartDataSource;
2502
+ categories: ChartDataSource;
2503
+ values: ChartDataSource;
2504
+ x: ChartDataSource;
2505
+ y: ChartDataSource;
2506
+ size: ChartDataSource;
2507
+ fill: ChartFillInfo;
2508
+ line: ChartLineInfo;
2509
+ marker: ChartMarkerInfo | null;
2510
+ smooth: boolean | null;
2511
+ points: ChartPointInfo[];
2512
+ labels: ChartLabelsInfo | null;
2513
+ }
2514
+
2515
+ export interface ChartPlotInfo {
2516
+ type: ChartPlotType;
2517
+ chartexLayout: string | null;
2518
+ barDirection: 'col' | 'bar' | null;
2519
+ grouping: ChartGrouping | null;
2520
+ varyColors: boolean;
2521
+ gapWidth: number | null;
2522
+ overlap: number | null;
2523
+ holeSize: number | null;
2524
+ firstSliceAngle: number | null;
2525
+ axisIds: number[];
2526
+ series: ChartSeriesInfo[];
2527
+ }
2528
+
2529
+ /** A chart or axis title: `text` for `Text`, `formula` for `Ref`, each empty otherwise. */
2530
+ export interface ChartTitleInfo {
2531
+ kind: ChartTitleKind;
2532
+ text: string;
2533
+ formula: string;
2534
+ }
2535
+
2536
+ export interface ChartAxisInfo {
2537
+ id: number;
2538
+ kind: ChartAxisKind;
2539
+ position: 'b' | 't' | 'l' | 'r';
2540
+ deleted: boolean;
2541
+ crossAxis: number;
2542
+ crosses: ChartAxisCrosses;
2543
+ crossesAt: number | null;
2544
+ min: number | null;
2545
+ max: number | null;
2546
+ majorUnit: number | null;
2547
+ minorUnit: number | null;
2548
+ logBase: number | null;
2549
+ reversed: boolean;
2550
+ numberFormat: string | null;
2551
+ sourceLinked: boolean;
2552
+ title: ChartTitleInfo;
2553
+ majorGridlines: boolean;
2554
+ minorGridlines: boolean;
2555
+ tickLabelPosition: string | null;
2556
+ }
2557
+
2558
+ /** The typed view of a chart. `source` is the rectangle every series was split from, `null` when they share none. */
2559
+ export interface ChartInfo {
2560
+ objectId: number;
2561
+ name: string;
2562
+ description: string;
2563
+ isChartex: boolean;
2564
+ isPivotChart: boolean;
2565
+ onChartsheet: boolean;
2566
+ title: ChartTitleInfo;
2567
+ autoTitleDeleted: boolean | null;
2568
+ legend: { position: ChartLegendPosition; overlay: boolean; hiddenSeries: number[] };
2569
+ blanksAs: ChartBlanksAs;
2570
+ plotVisibleOnly: boolean | null;
2571
+ date1904: boolean;
2572
+ style: number | null;
2573
+ plots: ChartPlotInfo[];
2574
+ axes: ChartAxisInfo[];
2575
+ hiddenCategories: number[];
2576
+ source: { range: string; direction: ChartSeriesDirection; headerRow: boolean; headerColumn: boolean } | null;
2577
+ }
2578
+
2579
+ /** A 0-based inclusive cell rectangle on sheet index `sheet`. */
2580
+ export interface ChartSheetRange {
2581
+ sheet: number;
2582
+ top: number;
2583
+ left: number;
2584
+ bottom: number;
2585
+ right: number;
2586
+ }
2587
+
2588
+ /** One resolved series; `values`, `states` (a {@link ChartPointState} each) and the optional `x` / `sizes` have `pointCount` entries. */
2589
+ export interface ChartDataSeries {
2590
+ plotIndex: number;
2591
+ idx: number;
2592
+ name: string | null;
2593
+ /** Number format of the values (the y values in the XY domain). */
2594
+ formatCode: string;
2595
+ /** Number format of the x values; empty outside the XY domain. */
2596
+ xFormatCode: string;
2597
+ filtered: boolean;
2598
+ values: Float64Array;
2599
+ states: Uint8Array;
2600
+ x: Float64Array | null;
2601
+ sizes: Float64Array | null;
2602
+ ranges: {
2603
+ name: ChartSheetRange[];
2604
+ categories: ChartSheetRange[];
2605
+ values: ChartSheetRange[];
2606
+ x: ChartSheetRange[];
2607
+ y: ChartSheetRange[];
2608
+ size: ChartSheetRange[];
2609
+ };
2610
+ }
2611
+
2612
+ /** Series resolved against the current cell values by Excel's rules. `unresolved` lists inputs that did not resolve; `axisId` names the axis of an `axis_title` entry. */
2613
+ export interface ChartData {
2614
+ domain: 'category' | 'xy';
2615
+ pointCount: number;
2616
+ categories: {
2617
+ labels: string[];
2618
+ levels: string[][];
2619
+ values: Float64Array | null;
2620
+ formatCode: string;
2621
+ generated: boolean;
2622
+ };
2623
+ series: ChartDataSeries[];
2624
+ titleText: string | null;
2625
+ axisTitleTexts: { axisId: number; text: string }[];
2626
+ unresolved: { seriesIdx: number; source: string; axisId: number }[];
2627
+ }
2628
+
2629
+ /** Options of `Workbook.insertChart`. An omitted `headerRow` / `headerColumn` follows Excel's detection, an omitted `title`
2630
+ * is Excel's automatic title and an empty one is no title. `placement` defaults to a two-cell anchor, and a zero
2631
+ * `widthEmu` / `heightEmu` means Excel's default frame. */
2632
+ export interface ChartInsertOptions {
2633
+ kind: ChartInsertKind;
2634
+ grouping?: ChartGrouping;
2635
+ source: string;
2636
+ direction?: ChartSeriesDirection;
2637
+ headerRow?: boolean;
2638
+ headerColumn?: boolean;
2639
+ title?: string;
2640
+ legend?: ChartLegendPosition;
2641
+ name?: string;
2642
+ description?: string;
2643
+ placement?: ImagePlacement;
2644
+ }
2645
+
2646
+ /** A patch leaves an omitted field unchanged; `null` removes the element. Colors are ARGB (`0xAARRGGBB`). */
2647
+ export interface ChartFillPatch {
2648
+ color?: number | null;
2649
+ transparency?: number | null;
2650
+ }
2651
+
2652
+ export interface ChartLinePatch {
2653
+ color?: number | null;
2654
+ transparency?: number | null;
2655
+ widthPt?: number | null;
2656
+ dash?: ChartLineDash | null;
2657
+ none?: boolean;
2658
+ }
2659
+
2660
+ export interface ChartMarkerPatch {
2661
+ symbol?: ChartMarkerSymbol;
2662
+ size?: number | null;
2663
+ fill?: ChartFillPatch;
2664
+ line?: ChartLinePatch;
2665
+ }
2666
+
2667
+ export interface ChartLabelsPatch {
2668
+ showValue?: boolean;
2669
+ showCategory?: boolean;
2670
+ showSeries?: boolean;
2671
+ showPercent?: boolean;
2672
+ showLegendKey?: boolean;
2673
+ separator?: string | null;
2674
+ position?: ChartLabelPosition | null;
2675
+ numberFormat?: string | null;
2676
+ fontColor?: number | null;
2677
+ fontSizePt?: number | null;
2678
+ }
2679
+
2680
+ /** An empty string for `name`, `categories` or `x` removes the reference; one for `values`, `y` or `size` is rejected. */
2681
+ export interface ChartSeriesPatch {
2682
+ name?: string;
2683
+ categories?: string;
2684
+ values?: string;
2685
+ x?: string;
2686
+ y?: string;
2687
+ size?: string;
2688
+ fill?: ChartFillPatch;
2689
+ line?: ChartLinePatch;
2690
+ marker?: ChartMarkerPatch | null;
2691
+ smooth?: boolean;
2692
+ labels?: ChartLabelsPatch | null;
2693
+ }
2694
+
2695
+ export interface ChartPointPatch {
2696
+ fill?: ChartFillPatch;
2697
+ line?: ChartLinePatch;
2698
+ marker?: ChartMarkerPatch | null;
2699
+ }
2700
+
2701
+ /** A field the plot type does not have is rejected; `holeSize` is 10..90 and doughnut only. */
2702
+ export interface ChartPlotPatch {
2703
+ gapWidth?: number;
2704
+ overlap?: number;
2705
+ firstSliceAngle?: number;
2706
+ varyColors?: boolean;
2707
+ holeSize?: number;
2708
+ }
2709
+
2710
+ /** `crossesAt` is read when `crosses` is `At`. `title` takes the forms of `setChartTitle`, so
2711
+ * `{ kind: ChartTitleKind.Auto }` gives the axis Excel's automatic title; `null` removes it. `null` on `logBase` makes
2712
+ * the axis linear and on `tickLabelPosition` (`nextTo`, `low`, `high`, `none`) restores the default. */
2713
+ export interface ChartAxisPatch {
2714
+ visible?: boolean;
2715
+ title?: string | null | { kind: ChartTitleKind; text?: string; formula?: string };
2716
+ min?: number | null;
2717
+ max?: number | null;
2718
+ majorUnit?: number | null;
2719
+ numberFormat?: string | null;
2720
+ majorGridlines?: boolean;
2721
+ reversed?: boolean;
2722
+ logBase?: number | null;
2723
+ crosses?: ChartAxisCrosses;
2724
+ crossesAt?: number;
2725
+ tickLabelPosition?: string | null;
2726
+ }
2727
+
2728
+ /** Overrides `previewChartData` applies to a copy of the chart; an omitted field keeps the chart's own value. */
2729
+ export interface ChartPreviewOverrides {
2730
+ source?: string;
2731
+ direction?: ChartSeriesDirection;
2732
+ headerRow?: boolean;
2733
+ headerColumn?: boolean;
2734
+ blanksAs?: ChartBlanksAs;
2735
+ plotVisibleOnly?: boolean;
2736
+ }
2737
+
2738
+ /** Result of `Workbook.getChart`; `chart` is `null` unless `status` is ok. */
2739
+ export interface ChartResult {
2740
+ status: Status;
2741
+ chart: ChartInfo | null;
2742
+ }
2743
+
2744
+ /** Result of `Workbook.getChartData` and `previewChartData`; `data` is `null` unless `status` is ok. */
2745
+ export interface ChartDataResult {
2746
+ status: Status;
2747
+ data: ChartData | null;
2748
+ }
2749
+
2750
+ /** Result of `Workbook.insertChart`; `objectId` is zero on failure. */
2751
+ export interface InsertChartResult {
2752
+ status: Status;
2753
+ objectId: number;
2754
+ }
2755
+
2756
+ /** Result of `Workbook.addChartSeries`; `seriesIdx` is the new series' `c:idx`, zero on failure. */
2757
+ export interface AddChartSeriesResult {
2758
+ status: Status;
2759
+ seriesIdx: number;
2760
+ }
2761
+
2307
2762
  /** Result of `Workbook.rangeStyleBases`; `xfIndices` is ascending and empty on failure. */
2308
2763
  export interface RangeStyleBasesResult {
2309
2764
  status: Status;
@@ -2317,14 +2772,14 @@ export interface RangeStyleSnapshotResult {
2317
2772
  bytes: Uint8Array;
2318
2773
  }
2319
2774
 
2320
- /** Result of `Workbook.snapshotImage`. `bytes` is an opaque, versioned capture to hand
2321
- * to `restoreImage`; it is empty on failure. */
2775
+ /** Result of `Workbook.snapshotDrawing`. `bytes` is an opaque, versioned capture to hand
2776
+ * to `restoreDrawing`; it is empty on failure. */
2322
2777
  export interface ImageSnapshotResult {
2323
2778
  status: Status;
2324
2779
  bytes: Uint8Array;
2325
2780
  }
2326
2781
 
2327
- /** Options of `Workbook.restoreImage`. With `newId` the capture is added on top as a
2782
+ /** Options of `Workbook.restoreDrawing`. With `newId` the capture is added on top as a
2328
2783
  * copy with a fresh id; otherwise a picture with the same id is replaced. */
2329
2784
  export interface RestoreImageOptions {
2330
2785
  newId?: boolean;
@@ -2846,16 +3301,74 @@ export interface Workbook {
2846
3301
  getImage(sheet: number, objectId: number): ImageResult;
2847
3302
  /** Inserts `bytes` as a picture; existing drawing content is kept. */
2848
3303
  insertImage(sheet: number, bytes: Uint8Array, opts?: ImageInsertOptions): InsertImageResult;
2849
- /** Removes the picture `objectId` and its media once nothing else references it. */
2850
- removeImage(sheet: number, objectId: number): Status;
2851
- /** Moves and resizes the picture `objectId`, keeping its id, crop, rotation and every other element. */
2852
- setImageAnchor(sheet: number, objectId: number, placement: ImagePlacement): Status;
2853
- /** Makes the picture `objectId` item `index` of `listDrawingObjects`, whose order is the stacking order (0 is the back). */
2854
- setImageZOrder(sheet: number, objectId: number, index: number): Status;
2855
- /** Captures the picture `objectId` with its list position, element and media as opaque bytes for `restoreImage`. */
2856
- snapshotImage(sheet: number, objectId: number): ImageSnapshotResult;
2857
- /** Puts a `snapshotImage` capture back and returns the picture's id: in place of a picture with the same id at its recorded position, or as a copy on top with `newId`. */
2858
- restoreImage(sheet: number, bytes: Uint8Array, opts?: RestoreImageOptions): InsertImageResult;
3304
+ /** Removes the picture or chart `objectId` and the parts only it reaches; other drawing content is kept. */
3305
+ removeDrawing(sheet: number, objectId: number): Status;
3306
+ /** Moves and resizes the picture or chart `objectId`, keeping its id, crop, rotation and every other element. */
3307
+ setDrawingAnchor(sheet: number, objectId: number, placement: ImagePlacement): Status;
3308
+ /** Makes the picture or chart `objectId` item `index` of `listDrawingObjects`, whose order is the stacking order (0 is the back). */
3309
+ setDrawingZOrder(sheet: number, objectId: number, index: number): Status;
3310
+ /** Captures the picture or chart `objectId` with its list position, element and dependent parts as opaque bytes for `restoreDrawing`. */
3311
+ snapshotDrawing(sheet: number, objectId: number): ImageSnapshotResult;
3312
+ /** Puts a `snapshotDrawing` capture back and returns the object's id: in place of an object with the same id at its recorded position, or as a copy on top with `newId`. */
3313
+ restoreDrawing(sheet: number, bytes: Uint8Array, opts?: RestoreImageOptions): InsertImageResult;
3314
+
3315
+ // Charts. A chart is addressed as `(sheet, objectId)`, the id `listDrawingObjects` reports for a `DrawingObjectKind.Chart`.
3316
+ /** Reads the typed view of the chart `objectId`. */
3317
+ getChart(sheet: number, objectId: number): ChartResult;
3318
+ /** Resolves the chart's series against the current cell values. */
3319
+ getChartData(sheet: number, objectId: number): ChartDataResult;
3320
+ /** Resolves the series as if `overrides` were applied to the chart; the workbook is not changed. */
3321
+ previewChartData(sheet: number, objectId: number, overrides: ChartPreviewOverrides): ChartDataResult;
3322
+ /** Creates a chart with filled caches and returns its object id. */
3323
+ insertChart(sheet: number, options: ChartInsertOptions): InsertChartResult;
3324
+ /** Replaces plot group `plot` with `kind`; `grouping` applies to column, bar, line and area. */
3325
+ setChartType(sheet: number, objectId: number, plot: number, kind: ChartInsertKind, grouping?: ChartGrouping): Status;
3326
+ /** Sets the chart title text, or removes the title with `null`. A {@link ChartTitleInfo} sets that kind, so `{ kind: ChartTitleKind.Auto }` returns the title to Excel's automatic one. */
3327
+ setChartTitle(
3328
+ sheet: number,
3329
+ objectId: number,
3330
+ title: string | null | { kind: ChartTitleKind; text?: string; formula?: string },
3331
+ ): Status;
3332
+ /** Sets the legend position (`None` removes it) and overlay; `hiddenSeries` (series `c:idx` values) replaces the hidden legend entries when given. */
3333
+ setChartLegend(
3334
+ sheet: number,
3335
+ objectId: number,
3336
+ position: ChartLegendPosition,
3337
+ overlay: boolean,
3338
+ hiddenSeries?: number[],
3339
+ ): Status;
3340
+ /** Patches the axis `axisId`. */
3341
+ setChartAxis(sheet: number, objectId: number, axisId: number, patch: ChartAxisPatch): Status;
3342
+ /** Sets how blanks are plotted and whether hidden cells are skipped; `Absent` and `null` remove the element. */
3343
+ setChartDisplay(sheet: number, objectId: number, blanksAs: ChartBlanksAs, plotVisibleOnly: boolean | null): Status;
3344
+ /** Patches the series with `c:idx` `seriesIdx` of plot group `plot`. */
3345
+ setChartSeries(sheet: number, objectId: number, plot: number, seriesIdx: number, patch: ChartSeriesPatch): Status;
3346
+ /** Patches a data point; `null` or an empty patch removes its formatting. */
3347
+ setChartPoint(
3348
+ sheet: number,
3349
+ objectId: number,
3350
+ plot: number,
3351
+ seriesIdx: number,
3352
+ pointIdx: number,
3353
+ patch: ChartPointPatch | null,
3354
+ ): Status;
3355
+ /** Patches plot group `plot`. */
3356
+ setChartPlot(sheet: number, objectId: number, plot: number, patch: ChartPlotPatch): Status;
3357
+ /** Replaces the chart filter: series by `c:idx` and categories by position are hidden. */
3358
+ setChartFilter(sheet: number, objectId: number, hiddenSeries: number[], hiddenCategories: number[]): Status;
3359
+ /** Appends a series to plot group `plot`; the patch must set `values` (`y` for a scatter plot). */
3360
+ addChartSeries(sheet: number, objectId: number, plot: number, patch: ChartSeriesPatch): AddChartSeriesResult;
3361
+ /** Removes the series with `c:idx` `seriesIdx` from plot group `plot`. */
3362
+ removeChartSeries(sheet: number, objectId: number, plot: number, seriesIdx: number): Status;
3363
+ /** Rebuilds every series from `source`, keeping the chart kind and each series' formatting by idx, and clears the filter. An omitted header flag follows Excel's detection. */
3364
+ setChartSource(
3365
+ sheet: number,
3366
+ objectId: number,
3367
+ source: string,
3368
+ direction: ChartSeriesDirection,
3369
+ headerRow?: boolean,
3370
+ headerColumn?: boolean,
3371
+ ): Status;
2859
3372
 
2860
3373
  /** Number of OOXML parts the reader carried through unchanged. */
2861
3374
  passthroughCount(): NumberResult;
Binary file