@libraz/formulon 0.15.1 → 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.
@@ -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
@@ -368,6 +372,13 @@ export enum PivotCalendar {
368
372
  Japanese = 1,
369
373
  }
370
374
 
375
+ /** Sibling item order of a pivot field. Mirrors `fm_pivot_sort_order_t`. */
376
+ export enum PivotSortOrder {
377
+ Descending = 0,
378
+ Ascending = 1,
379
+ Manual = 2,
380
+ }
381
+
371
382
  /** Pivot report layout form. Mirrors `fm_pivot_layout_t`. */
372
383
  export enum PivotReportLayout {
373
384
  Compact = 0,
@@ -383,6 +394,8 @@ export interface PivotWorksheetSource {
383
394
  name?: string;
384
395
  }
385
396
 
397
+ /** Return type of `Workbook.pivotCacheGetWorksheetSource(cacheId)`: the source metadata plus `status`;
398
+ * `ref`, `sheet` and `name` are empty strings when absent. */
386
399
  export interface PivotWorksheetSourceResult extends PivotWorksheetSource {
387
400
  status: Status;
388
401
  ref: string;
@@ -390,6 +403,7 @@ export interface PivotWorksheetSourceResult extends PivotWorksheetSource {
390
403
  name: string;
391
404
  }
392
405
 
406
+ /** Return type of `Workbook.pivotGetLayout(sheet, pivotIdx)`: `status` plus the report `layout`. */
393
407
  export interface PivotReportLayoutResult {
394
408
  status: Status;
395
409
  layout: PivotReportLayout;
@@ -412,6 +426,9 @@ export interface PivotFieldSpec {
412
426
  sourceName: string;
413
427
  customName?: string;
414
428
  axis: PivotAxis;
429
+ /** Subtotal on the group's own heading row (default `true`, as in Excel);
430
+ * `false` heads the group with a label-only row and closes it with an
431
+ * `"<item> Total"` row. */
415
432
  subtotalTop?: boolean;
416
433
  /** `numFmtId` as a decimal string (built-in or from `addNumFmt`). */
417
434
  numberFormat?: string;
@@ -781,7 +798,7 @@ export interface SheetFormatDefaultsResult extends SheetFormatDefaults {
781
798
  status: Status;
782
799
  /** Character units the sheet lays columns out with: `defaultColWidth` when set, else 8.43. */
783
800
  effectiveDefaultColWidth: number;
784
- /** 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. */
785
802
  effectiveDefaultRowHeight: number;
786
803
  }
787
804
 
@@ -1316,6 +1333,7 @@ export interface ConditionalFormatEntry {
1316
1333
  /** Engaged for `iconSet` rules. */
1317
1334
  readonly iconSet?: {
1318
1335
  readonly name: number;
1336
+ /** Exactly N-1 thresholds for an N-icon set (the floor is `floor`, not a threshold). A formula-typed value carries no leading `=`. */
1319
1337
  readonly thresholds: ReadonlyArray<CfValueObjectInput>;
1320
1338
  readonly reverse: boolean;
1321
1339
  readonly showValue: boolean;
@@ -1383,6 +1401,7 @@ export interface ConditionalFormatInput {
1383
1401
  /** Payload for type 4 (`iconSet`). `name` is `formulon::cf::IconSetName` ordinal. */
1384
1402
  iconSet?: {
1385
1403
  name: number;
1404
+ /** Exactly N-1 thresholds for an N-icon set (the floor is `floor`, not a threshold); any other count is rejected with `kInvalidArgument`. A formula-typed value is stored without its leading `=`. */
1386
1405
  thresholds: ReadonlyArray<CfValueObjectInput>;
1387
1406
  reverse?: boolean;
1388
1407
  showValue?: boolean;
@@ -1503,6 +1522,9 @@ export interface FontRecord {
1503
1522
  hasCharset: boolean;
1504
1523
  /** OOXML charset codepage id (e.g. 128 = Shift_JIS). */
1505
1524
  charset: number;
1525
+ /** Whether the font carries a `<sz>` element. A differential font without
1526
+ * one leaves the size unchanged; on input it defaults to whether `size` is given. */
1527
+ hasSize: boolean;
1506
1528
  /** `<scheme>` theme link: 0=absent, 1=major, 2=minor. Meaningful only on
1507
1529
  * a workbook that carries a theme part. */
1508
1530
  scheme: number;
@@ -1672,6 +1694,7 @@ export interface DxfRecord {
1672
1694
  protectionXml?: string;
1673
1695
  }
1674
1696
 
1697
+ /** Return type of `Workbook.getDxf(dxfIndex)`: `status` plus the `DxfRecord` fields. */
1675
1698
  export interface DxfResult extends DxfRecord {
1676
1699
  status: Status;
1677
1700
  }
@@ -1880,6 +1903,141 @@ export enum AnchorEditAs {
1880
1903
  Absolute = 2,
1881
1904
  }
1882
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
+
1883
2041
  /** How a colour was resolved. Mirrors `fm_color_resolution_t`. `Exact` is a literal or workbook-supplied
1884
2042
  * colour; `DefaultTheme` / `ThemeUnparseable` mean the current Excel Office (Aptos) theme was used because
1885
2043
  * the theme part is absent / unparseable; `IndexOutOfRange` is black; `AutoContext` is an automatic colour
@@ -2263,7 +2421,7 @@ export interface ImageInsertOptions {
2263
2421
  heightEmu?: number;
2264
2422
  }
2265
2423
 
2266
- /** 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. */
2267
2425
  export interface InsertImageResult {
2268
2426
  status: Status;
2269
2427
  objectId: number;
@@ -2285,6 +2443,322 @@ export interface ImagePlacement {
2285
2443
  heightEmu?: number;
2286
2444
  }
2287
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
+
2288
2762
  /** Result of `Workbook.rangeStyleBases`; `xfIndices` is ascending and empty on failure. */
2289
2763
  export interface RangeStyleBasesResult {
2290
2764
  status: Status;
@@ -2298,14 +2772,14 @@ export interface RangeStyleSnapshotResult {
2298
2772
  bytes: Uint8Array;
2299
2773
  }
2300
2774
 
2301
- /** Result of `Workbook.snapshotImage`. `bytes` is an opaque, versioned capture to hand
2302
- * 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. */
2303
2777
  export interface ImageSnapshotResult {
2304
2778
  status: Status;
2305
2779
  bytes: Uint8Array;
2306
2780
  }
2307
2781
 
2308
- /** 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
2309
2783
  * copy with a fresh id; otherwise a picture with the same id is replaced. */
2310
2784
  export interface RestoreImageOptions {
2311
2785
  newId?: boolean;
@@ -2481,6 +2955,8 @@ export interface Workbook {
2481
2955
  * running a `recalc`/`recalcParallel` against the handle. */
2482
2956
  delete(): void;
2483
2957
 
2958
+ /** Serialises the workbook to an in-memory `.xlsx` byte stream. `bytes` is `null` and
2959
+ * `status` a `kIo*` code on archive / writer failure. */
2484
2960
  save(): SaveResult;
2485
2961
  /** Serialises using an explicit container `format` (see `WorkbookFormat`). */
2486
2962
  saveAs(format: WorkbookFormat | number): SaveResult;
@@ -2488,6 +2964,9 @@ export interface Workbook {
2488
2964
  saveWithDiagnostics(format: WorkbookFormat | number): SaveDiagnosticsResult;
2489
2965
  /** Returns the loss counters captured when this handle was loaded. */
2490
2966
  readDiagnostics(): ReadDiagnosticsResult;
2967
+ /** Appends a sheet. Fails with `kInvalidSheetName` when the name is empty, longer than 31 UTF-16 units,
2968
+ * contains one of `: \ / ? * [ ]`, or collides case-insensitively (Unicode simple case folding) with an
2969
+ * existing sheet, and with `kSheetCountLimitExceeded` at the maximum sheet count. */
2491
2970
  addSheet(name: string): Status;
2492
2971
  /** Removes the sheet at `index`. */
2493
2972
  removeSheet(index: number): Status;
@@ -2495,16 +2974,21 @@ export interface Workbook {
2495
2974
  renameSheet(index: number, newName: string): Status;
2496
2975
  /** Moves the sheet from `fromIdx` to `toIdx` (post-removal index). */
2497
2976
  moveSheet(fromIdx: number, toIdx: number): Status;
2977
+ /** Number of sheets. */
2498
2978
  sheetCount(): NumberResult;
2979
+ /** Display name of the sheet at `idx`; `kInvalidArgument` when `idx` is out of range. */
2499
2980
  sheetName(idx: number): StringResult;
2500
2981
 
2982
+ /** Stores a numeric literal. NaN and infinity are rejected with `kInvalidArgument`; so is an out-of-range `sheet`. */
2501
2983
  setNumber(sheet: number, row: number, col: number, value: number): Status;
2984
+ /** Stores a boolean literal. */
2502
2985
  setBool(sheet: number, row: number, col: number, value: boolean): Status;
2503
2986
  /** Stores a static Excel error literal; `errorCode` is an ErrorCode
2504
2987
  * ordinal. Unlike `setNumber`/`setBool`/`setText`, an omitted
2505
2988
  * `errorCode` has no sane zero-value default, so it is rejected
2506
2989
  * rather than silently writing error code 0 (`#NULL!`). */
2507
2990
  setError(sheet: number, row: number, col: number, errorCode: number): Status;
2991
+ /** Stores a text literal. */
2508
2992
  setText(sheet: number, row: number, col: number, text: string): Status;
2509
2993
  /** Stores (or, when empty, clears) the cell's OOXML phonetic guide (`<rPh>`). */
2510
2994
  setCellPhonetic(sheet: number, row: number, col: number, phonetic: string): Status;
@@ -2519,11 +3003,14 @@ export interface Workbook {
2519
3003
  * that has runs; every value setter clears both, so call it after the
2520
3004
  * cell's text. */
2521
3005
  setCellPhoneticProperties(sheet: number, row: number, col: number, properties: PhoneticProperties): Status;
3006
+ /** Stores a blank literal at the cell; equivalent to clearing it. */
2522
3007
  setBlank(sheet: number, row: number, col: number): Status;
2523
3008
  /** Stores a formula. Returns `kParserUnexpectedToken` and changes nothing when the text
2524
3009
  * does not parse: a syntax error, or a built-in called through a sheet / workbook qualifier. */
2525
3010
  setFormula(sheet: number, row: number, col: number, formula: string): Status;
2526
3011
 
3012
+ /** Reads the cell's cached value, as of the most recent recalc; call `recalc` first after mutating cells.
3013
+ * Fails with `kInvalidArgument` when `sheet`, `row` or `col` is out of range. */
2527
3014
  getValue(sheet: number, row: number, col: number): CellResult;
2528
3015
 
2529
3016
  /** The stored A1 formula (leading `=` included), or `formula: null` for a cell that holds none.
@@ -2616,6 +3103,9 @@ export interface Workbook {
2616
3103
  * `IterativeProgressCallback` cut the pass short. */
2617
3104
  partialRecalc(viewport: RecalcViewport): PartialRecalcResult;
2618
3105
 
3106
+ /** Sets iterative calculation. When disabled (the default) cyclic references surface `#REF!`.
3107
+ * `maxIterations` is clamped to `[1, 32767]` (Excel's own limit) and `getIterative` reports the
3108
+ * clamped value; `maxChange` is the absolute convergence threshold. */
2619
3109
  setIterative(enabled: boolean, maxIterations: number, maxChange: number): Status;
2620
3110
  /** Reads back the stored iterative-calculation settings. The cap and
2621
3111
  * threshold are the stored values even while `enabled` is false, so a
@@ -2640,6 +3130,7 @@ export interface Workbook {
2640
3130
  * here so the UI can mirror Excel's user-visible state.
2641
3131
  */
2642
3132
  calcMode(): NumberResult<CalcMode>;
3133
+ /** Sets the calc mode metadata; it does not change evaluation. Returns `kInvalidArgument` for a value outside `CalcMode`. */
2643
3134
  setCalcMode(mode: CalcMode): Status;
2644
3135
 
2645
3136
  /**
@@ -2667,13 +3158,17 @@ export interface Workbook {
2667
3158
  * is rejected rather than rolled into the next year.
2668
3159
  */
2669
3160
  pinnedNow(): PinnedNowResult;
3161
+ /** Pins the workbook clock to a local civil instant; see `pinnedNow` for the accepted ranges. */
2670
3162
  setPinnedNow(year: number, month: number, day: number, hour: number, minute: number, second: number): Status;
3163
+ /** Releases the pin so the clock follows the host again. Clearing an unpinned workbook succeeds and does nothing. */
2671
3164
  clearPinnedNow(): Status;
2672
3165
 
2673
3166
  /** Full formula-behaviour profile id. Defaults to `win-365-en_US`.
2674
3167
  * Pick another locale or host with any {@link ExcelProfileId}.
2675
3168
  */
2676
3169
  excelProfileId(): StringResult<ExcelProfileId>;
3170
+ /** Selects the formula-behaviour profile; `kInvalidArgument` for an id that is not an {@link ExcelProfileId}.
3171
+ * Cached formula values are not recomputed until the next `recalc()`. */
2677
3172
  setExcelProfileId(profileId: ExcelProfileId): Status;
2678
3173
 
2679
3174
  /**
@@ -2711,7 +3206,9 @@ export interface Workbook {
2711
3206
  /** Reads the `idx`-th counted coordinate, `idx` in `[0, cellCount)`, ordered by `(row, col)` ascending. */
2712
3207
  cellAt(sheet: number, idx: number): CellEntry;
2713
3208
 
3209
+ /** Number of defined names, workbook- and sheet-scoped alike. */
2714
3210
  definedNameCount(): NumberResult;
3211
+ /** Reads the `idx`-th defined name with its scope; `kInvalidArgument` when `idx` is out of range. */
2715
3212
  definedNameAt(idx: number): DefinedNameEntry;
2716
3213
  /** Adds, replaces, or (when `formula` is empty) removes a workbook-
2717
3214
  * scoped defined name. A non-empty `formula` that does not parse is
@@ -2722,13 +3219,18 @@ export interface Workbook {
2722
3219
  * that does not parse is rejected with `kParserUnexpectedToken`. */
2723
3220
  setDefinedNameScoped(name: string, formula: string, localSheetId: number): Status;
2724
3221
 
3222
+ /** Number of worksheet tables in the workbook. */
2725
3223
  tableCount(): NumberResult;
3224
+ /** Reads the `idx`-th table's identifying metadata; `kInvalidArgument` when `idx` is out of range. */
2726
3225
  tableAt(idx: number): TableEntry;
3226
+ /** Creates a worksheet table; `index` of the result is its workbook-wide table index (see `tableAt`).
3227
+ * `input.columns` must hold one unique, non-empty header per column of `input.ref`. */
2727
3228
  createTable(input: TableInput): AddStyleResult;
2728
3229
  /** Partially updates a table. Omitted fields preserve their current
2729
3230
  * values. A supplied `ref` must keep the table's existing column count;
2730
3231
  * an empty `styleName` clears the style. */
2731
3232
  updateTable(idx: number, input: TableUpdateInput): Status;
3233
+ /** Removes the table at `idx`. */
2732
3234
  removeTable(idx: number): Status;
2733
3235
 
2734
3236
  /** Reads the complete worksheet-level `<autoFilter>` XML fragment. */
@@ -2754,10 +3256,15 @@ export interface Workbook {
2754
3256
  /** Table counterparts, addressed by the workbook-wide table index
2755
3257
  * (`tableAt`). */
2756
3258
  getTableAutoFilter(table: number): AutoFilterResult;
3259
+ /** Replaces the table's AutoFilter. Row visibility is unchanged. */
2757
3260
  setTableAutoFilter(table: number, filter: AutoFilter): Status;
3261
+ /** Removes the table's AutoFilter. Row visibility is unchanged. */
2758
3262
  removeTableAutoFilter(table: number): Status;
3263
+ /** Hides every body row the table's criteria exclude and shows the rest. */
2759
3264
  applyTableAutoFilter(table: number): Status;
3265
+ /** Drops every column criterion and shows all body rows. */
2760
3266
  clearTableAutoFilter(table: number): Status;
3267
+ /** Evaluates the table's AutoFilter without changing the sheet. */
2761
3268
  evaluateTableAutoFilter(table: number): AutoFilterEvalResult;
2762
3269
 
2763
3270
  /** Checks `value` against the validation rule covering `(row, col)` without
@@ -2780,6 +3287,8 @@ export interface Workbook {
2780
3287
  removeThreadedComment(sheet: number, id: string): Status;
2781
3288
  /** Lists the workbook's persons. */
2782
3289
  getPersons(): PersonsResult;
3290
+ /** Appends a person to the workbook's person list. Fails with `kThreadedCommentInvalid` when the id is
3291
+ * malformed or already listed, or the display name is empty. */
2783
3292
  addPerson(person: Person): Status;
2784
3293
  /** Fails while a threaded comment or mention still names the person. */
2785
3294
  removePerson(id: string): Status;
@@ -2792,18 +3301,78 @@ export interface Workbook {
2792
3301
  getImage(sheet: number, objectId: number): ImageResult;
2793
3302
  /** Inserts `bytes` as a picture; existing drawing content is kept. */
2794
3303
  insertImage(sheet: number, bytes: Uint8Array, opts?: ImageInsertOptions): InsertImageResult;
2795
- /** Removes the picture `objectId` and its media once nothing else references it. */
2796
- removeImage(sheet: number, objectId: number): Status;
2797
- /** Moves and resizes the picture `objectId`, keeping its id, crop, rotation and every other element. */
2798
- setImageAnchor(sheet: number, objectId: number, placement: ImagePlacement): Status;
2799
- /** Makes the picture `objectId` item `index` of `listDrawingObjects`, whose order is the stacking order (0 is the back). */
2800
- setImageZOrder(sheet: number, objectId: number, index: number): Status;
2801
- /** Captures the picture `objectId` with its list position, element and media as opaque bytes for `restoreImage`. */
2802
- snapshotImage(sheet: number, objectId: number): ImageSnapshotResult;
2803
- /** 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`. */
2804
- 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;
2805
3372
 
3373
+ /** Number of OOXML parts the reader carried through unchanged. */
2806
3374
  passthroughCount(): NumberResult;
3375
+ /** Reads the path of the `idx`-th passthrough part; `kInvalidArgument` when `idx` is out of range. */
2807
3376
  passthroughAt(idx: number): PassthroughEntry;
2808
3377
 
2809
3378
  /** Returns the number of PivotTables anchored on `sheet`. */
@@ -2895,19 +3464,23 @@ export interface Workbook {
2895
3464
 
2896
3465
  /** Number of fields configured on the pivot. */
2897
3466
  pivotFieldCount(sheet: number, pivotIdx: number): NumberResult;
2898
- /** Appends a new field. Returns `{ status, index: fieldIdx }`. */
3467
+ /** Appends a new field. Returns `{ status, index: fieldIdx }`. A field
3468
+ * added on the row or column axis is appended to that axis's order. */
2899
3469
  pivotFieldAdd(sheet: number, pivotIdx: number, spec: PivotFieldSpec): AddStyleResult;
2900
- /** Drops every field from the pivot. */
3470
+ /** Drops every field from the pivot, emptying the row and column orders. */
2901
3471
  pivotFieldClear(sheet: number, pivotIdx: number): Status;
2902
- /** Sets the axis of pivot field `fieldIdx`. */
3472
+ /** Sets the axis of pivot field `fieldIdx`. Moving onto the row or column
3473
+ * axis appends the field to that axis's order; moving off removes it. */
2903
3474
  pivotFieldSetAxis(sheet: number, pivotIdx: number, fieldIdx: number, axis: PivotAxis): Status;
2904
- /** Sets the sort directive on pivot field `fieldIdx`. Pass an empty
2905
- * `byField` to clear the by-field key. */
2906
- pivotFieldSetSort(sheet: number, pivotIdx: number, fieldIdx: number, ascending: boolean, byField: string): Status;
3475
+ /** Sets the sibling order of pivot field `fieldIdx`. `PivotSortOrder.Manual`
3476
+ * keeps items in `pivotFieldAddItem` order and takes no `byField`; for the
3477
+ * other orders an empty `byField` sorts by label. */
3478
+ pivotFieldSetSort(sheet: number, pivotIdx: number, fieldIdx: number, order: PivotSortOrder, byField: string): Status;
2907
3479
  /** Sets the `subtotal_top` flag on pivot field `fieldIdx`. */
2908
3480
  pivotFieldSetSubtotalTop(sheet: number, pivotIdx: number, fieldIdx: number, top: boolean): Status;
2909
3481
  /** Appends a manual-filter item to pivot field `fieldIdx`, addressed by
2910
- * its label. The item carries no cache binding, so the filter engine
3482
+ * its label. The item binds to the first shared item of the cache field
3483
+ * that renders as `name` (unbound when none does), and the filter engine
2911
3484
  * matches source records by comparing their rendered label against
2912
3485
  * `name`. An empty `name` therefore cannot express the blank item,
2913
3486
  * which has no label of its own; use `pivotFieldAddItemAt`. */
@@ -2964,7 +3537,9 @@ export interface Workbook {
2964
3537
  pivotFieldSetNumberFormat(sheet: number, pivotIdx: number, fieldIdx: number, utf8: string): Status;
2965
3538
 
2966
3539
  /** Replaces the row-axis field order with `indices`. Each entry must
2967
- * be `< pivotFieldCount`. Pass an empty array to clear. */
3540
+ * be `< pivotFieldCount` and appear once. The list is the axis's whole
3541
+ * membership: listed fields move onto the row axis and fields left out
3542
+ * come off it. Pass an empty array to clear. */
2968
3543
  pivotSetRowFieldOrder(sheet: number, pivotIdx: number, indices: ReadonlyArray<number>): Status;
2969
3544
  /** Replaces the column-axis field order. Same contract as rows. */
2970
3545
  pivotSetColFieldOrder(sheet: number, pivotIdx: number, indices: ReadonlyArray<number>): Status;