@libraz/formulon 0.17.0 → 0.18.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.
@@ -7,7 +7,7 @@
7
7
  // EXPORT_NAME=createFormulon / EXPORT_ES6=1 and share this surface. It
8
8
  // returns a Promise resolving to the Module surface declared below.
9
9
  //
10
- // Mirror of `EMSCRIPTEN_BINDINGS(formulon)` in `src/wasm/embind.cpp`.
10
+ // Mirror of the embind registration in `src/wasm/parts/bindings_register.cpp`.
11
11
  // Keep this file in sync when adding or removing bindings.
12
12
 
13
13
  /** `fm_value_kind_t` ordinals (mirror of `fm_value_kind_t`). */
@@ -22,8 +22,13 @@ export enum ValueKind {
22
22
  Lambda = 7,
23
23
  }
24
24
 
25
- /** Status carried by binding result envelopes. Argument validation may
26
- * throw `TypeError` or `RangeError` before returning a result. */
25
+ /** Status carried by binding result envelopes. Positional arguments are
26
+ * validated before any engine call, identically on both packages: a
27
+ * missing required argument, a value of the wrong type, or a primitive or
28
+ * `null` where an object is declared throws `TypeError`, and an
29
+ * out-of-range integer throws `RangeError`. A malformed argument a method
30
+ * reports as a status instead -- an array of the wrong length, a value that
31
+ * is not callable -- carries `kInvalidArgument` (2). */
27
32
  export interface Status {
28
33
  /** True when the underlying C ABI returned `kOk`. */
29
34
  ok: boolean;
@@ -200,21 +205,62 @@ export interface DefinedNameEntry {
200
205
  formula?: string;
201
206
  /** -1 for workbook scope; otherwise a 0-based sheet index. */
202
207
  localSheetId?: number;
208
+ /** The note Excel shows in the Name Manager; empty when none. */
209
+ comment?: string;
210
+ /** Whether the name is hidden from the Name Manager. */
211
+ hidden?: boolean;
203
212
  }
204
213
 
205
- /** Return type of `Workbook.tableAt(idx)`. */
214
+ /** A table column's totals-row function (`ST_TotalsRowFunction`). */
215
+ export type TableTotalsRowFunction =
216
+ | 'none'
217
+ | 'sum'
218
+ | 'min'
219
+ | 'max'
220
+ | 'average'
221
+ | 'count'
222
+ | 'countNums'
223
+ | 'stdDev'
224
+ | 'var'
225
+ | 'custom';
226
+
227
+ /** One column of `TableEntry.columns`. `totalsRowFormula` is the `custom`
228
+ * function's formula (no leading `=`), empty otherwise. */
229
+ export interface TableColumnEntry {
230
+ name: string;
231
+ totalsRowFunction: TableTotalsRowFunction;
232
+ totalsRowLabel: string;
233
+ totalsRowFormula: string;
234
+ }
235
+
236
+ /** Return type of `Workbook.tableAt(idx)`. `styleName` is empty without a
237
+ * style and may name a custom style (`getTableStyle`); `hasStyleInfo` is
238
+ * false when the table has no `<tableStyleInfo>` (the toggles then read
239
+ * false). The row counts are 0 or 1. */
206
240
  export interface TableEntry {
207
241
  status: Status;
208
242
  name?: string;
209
243
  displayName?: string;
210
244
  ref?: string;
211
245
  sheetIndex?: number;
246
+ styleName?: string;
247
+ hasStyleInfo?: boolean;
248
+ showFirstColumn?: boolean;
249
+ showLastColumn?: boolean;
250
+ showRowStripes?: boolean;
251
+ showColumnStripes?: boolean;
252
+ headerRowCount?: number;
253
+ totalsRowCount?: number;
254
+ columns?: TableColumnEntry[];
212
255
  }
213
256
 
214
257
  /** Authoring input for a worksheet table. `columns` must have exactly one
215
- * name per column in `ref`; `styleName` follows Excel's built-in TableStyle
216
- * names. With `headerRow` (the default), the caller still writes the header
217
- * cells: Excel expects the first row of `ref` to hold the column names. */
258
+ * name per column in `ref`; `styleName` names a built-in TableStyle or a
259
+ * custom style. A styled table starts with row stripes on and the other
260
+ * toggles off; a supplied toggle overrides that (and, without `styleName`,
261
+ * writes an unnamed style element). With `headerRow` (the default), the
262
+ * caller still writes the header cells: Excel expects the first row of `ref`
263
+ * to hold the column names. */
218
264
  export interface TableInput {
219
265
  sheetIndex: number;
220
266
  ref: string;
@@ -222,21 +268,112 @@ export interface TableInput {
222
268
  displayName?: string;
223
269
  columns: string[];
224
270
  styleName?: string;
271
+ showFirstColumn?: boolean;
272
+ showLastColumn?: boolean;
273
+ showRowStripes?: boolean;
274
+ showColumnStripes?: boolean;
225
275
  headerRow?: boolean;
226
276
  totalsRow?: boolean;
227
277
  }
228
278
 
229
279
  /** Partial table metadata update. Omitted fields preserve their existing
230
- * values; an empty `styleName` explicitly removes the table style. When
231
- * omitted, `ref` also preserves the current range. `headerRow` and
232
- * `totalsRow` update their flags only when supplied. */
280
+ * values; an empty `styleName` explicitly removes the table style, while a
281
+ * new name keeps the four toggles. When omitted, `ref` also preserves the
282
+ * current range. `headerRow` and `totalsRow` update their flags only when
283
+ * supplied; turning `totalsRow` on writes each column's totals cell on the
284
+ * last row of `ref` (see `setTableColumnTotals`). `name` renames the table
285
+ * (`displayName` follows it unless supplied), with `createTable`'s
286
+ * uniqueness rule, and rewrites structured references to the old name in
287
+ * cell, defined-name, conditional-format, validation and chart formulas; a
288
+ * bare table name used as a reference is not rewritten. The update is
289
+ * all-or-nothing. */
233
290
  export interface TableUpdateInput {
234
291
  ref?: string;
292
+ name?: string;
293
+ displayName?: string;
235
294
  styleName?: string;
295
+ showFirstColumn?: boolean;
296
+ showLastColumn?: boolean;
297
+ showRowStripes?: boolean;
298
+ showColumnStripes?: boolean;
236
299
  headerRow?: boolean;
237
300
  totalsRow?: boolean;
238
301
  }
239
302
 
303
+ /** Totals-row settings of one table column (`setTableColumnTotals`).
304
+ * `function` defaults to `'none'`; `formula` is required for `'custom'`. */
305
+ export interface TableColumnTotalsInput {
306
+ function?: TableTotalsRowFunction;
307
+ label?: string;
308
+ formula?: string;
309
+ }
310
+
311
+ /** A region of a custom table style (`ST_TableStyleType`). The PivotTable
312
+ * regions apply only to styles a PivotTable uses. */
313
+ export type TableStyleElementType =
314
+ | 'wholeTable'
315
+ | 'headerRow'
316
+ | 'totalRow'
317
+ | 'firstColumn'
318
+ | 'lastColumn'
319
+ | 'firstRowStripe'
320
+ | 'secondRowStripe'
321
+ | 'firstColumnStripe'
322
+ | 'secondColumnStripe'
323
+ | 'firstHeaderCell'
324
+ | 'lastHeaderCell'
325
+ | 'firstTotalCell'
326
+ | 'lastTotalCell'
327
+ | 'firstSubtotalColumn'
328
+ | 'secondSubtotalColumn'
329
+ | 'thirdSubtotalColumn'
330
+ | 'firstSubtotalRow'
331
+ | 'secondSubtotalRow'
332
+ | 'thirdSubtotalRow'
333
+ | 'blankRow'
334
+ | 'firstColumnSubheading'
335
+ | 'secondColumnSubheading'
336
+ | 'thirdColumnSubheading'
337
+ | 'firstRowSubheading'
338
+ | 'secondRowSubheading'
339
+ | 'thirdRowSubheading'
340
+ | 'pageFieldLabels'
341
+ | 'pageFieldValues';
342
+
343
+ /** One element of a custom table style. `size` is the stripe band size
344
+ * (default 1); `dxfId` indexes the differential formats (`addDxf`) and is
345
+ * absent for a region the style lists without formatting. */
346
+ export interface TableStyleElement {
347
+ type: TableStyleElementType;
348
+ size?: number;
349
+ dxfId?: number;
350
+ }
351
+
352
+ /** A custom table / PivotTable style (`setTableStyle`). `pivot` / `table`
353
+ * (default true) say which objects may use it. */
354
+ export interface TableStyle {
355
+ name: string;
356
+ pivot?: boolean;
357
+ table?: boolean;
358
+ elements?: TableStyleElement[];
359
+ }
360
+
361
+ /** Return type of `Workbook.getTableStyle(index)`; empty on failure. */
362
+ export interface TableStyleResult {
363
+ status: Status;
364
+ name: string;
365
+ pivot: boolean;
366
+ table: boolean;
367
+ elements: TableStyleElement[];
368
+ }
369
+
370
+ /** Return type of `Workbook.getTableStyleDefaults()`; empty when unset. */
371
+ export interface TableStyleDefaultsResult {
372
+ status: Status;
373
+ tableStyle: string;
374
+ pivotStyle: string;
375
+ }
376
+
240
377
  /** Return type of `Workbook.passthroughAt(idx)`. */
241
378
  export interface PassthroughEntry {
242
379
  status: Status;
@@ -452,6 +589,31 @@ export interface PivotDataFieldSpec {
452
589
  showAsBaseItem?: number;
453
590
  }
454
591
 
592
+ /** Table style and toggles of a PivotTable (`pivotSetStyleInfo`). An omitted
593
+ `name` writes the style element without a style name; flags default to
594
+ false. */
595
+ export interface PivotStyleInfo {
596
+ name?: string;
597
+ showRowHeaders?: boolean;
598
+ showColHeaders?: boolean;
599
+ showRowStripes?: boolean;
600
+ showColStripes?: boolean;
601
+ showLastColumn?: boolean;
602
+ }
603
+
604
+ /** Return type of `Workbook.pivotGetStyleInfo(...)`. `present` is false when
605
+ the definition has no style element (the other fields are then empty). */
606
+ export interface PivotStyleInfoResult {
607
+ status: Status;
608
+ present: boolean;
609
+ name: string;
610
+ showRowHeaders: boolean;
611
+ showColHeaders: boolean;
612
+ showRowStripes: boolean;
613
+ showColStripes: boolean;
614
+ showLastColumn: boolean;
615
+ }
616
+
455
617
  /** Return type of `Workbook.pivotGetGrandTotals(...)`. */
456
618
  export interface PivotGrandTotalsResult {
457
619
  status: Status;
@@ -493,6 +655,12 @@ export interface PivotFieldResult {
493
655
  /** `-1` when unset. */
494
656
  dateStartSerial: number;
495
657
  dateEndSerial: number;
658
+ /** Whether the automatic subtotal shows; `false` whenever `subtotalFns`
659
+ * is non-empty, since custom functions replace it. */
660
+ defaultSubtotal: boolean;
661
+ /** Custom subtotal functions (`pivotFieldAddSubtotalFn`), in ascending
662
+ * `PivotAggregation` order. */
663
+ subtotalFns: PivotAggregation[];
496
664
  }
497
665
 
498
666
  /** Return type of `Workbook.pivotFieldItemAt(...)`. */
@@ -542,12 +710,11 @@ export interface PivotFilterSpec {
542
710
  /** Return type of `Workbook.pivotFilterAt(...)`: the stored filter plus a
543
711
  * status envelope. Field names and semantics match `PivotFilterSpec`.
544
712
  *
545
- * The active-filter list is **session state**. An entry added through
546
- * `pivotFilterAdd` affects evaluation only while the workbook handle
547
- * lives and is not written by `save`. Conversely a `<filters>` block
548
- * Excel wrote is preserved verbatim on save but does not appear here, so
549
- * `pivotFilterCount` reports only what this session added. The filter
550
- * surface that does persist is pivot field item visibility. */
713
+ * The filter list is saved as the definition's `<filters>` block. A loaded
714
+ * file's caption contains / begins-with, top-N count, value greater-than /
715
+ * between and date-between entries appear here, naming their field by
716
+ * source name. Its other entries are not listed, still filter, survive
717
+ * `pivotFilterClear` / `pivotFilterRemoveAt`, and are saved verbatim. */
551
718
  export interface PivotFilterResult {
552
719
  status: Status;
553
720
  axis: number;
@@ -598,10 +765,11 @@ export enum ErrorCode {
598
765
  *
599
766
  * - `Auto` — recalc on every input change (Excel default).
600
767
  * - `Manual` — only recalc when explicitly requested.
601
- * - `AutoNoTable` — recalc on every change EXCEPT data-table cells.
768
+ * - `AutoNoTable` — recalc on every change EXCEPT data-table cells, which
769
+ * `recalcDataTables()` computes on demand.
602
770
  *
603
- * Round-trip metadata only — the engine recalcs all dirty cells
604
- * regardless of which mode is set.
771
+ * Round-trip metadata apart from `AutoNoTable` — the engine recalcs all
772
+ * dirty cells regardless of which other mode is set.
605
773
  */
606
774
  export enum CalcMode {
607
775
  Auto = 0,
@@ -609,6 +777,12 @@ export enum CalcMode {
609
777
  AutoNoTable = 2,
610
778
  }
611
779
 
780
+ /** Reference notation formulas are shown in (`<calcPr refMode>`). */
781
+ export enum RefMode {
782
+ A1 = 0,
783
+ R1C1 = 1,
784
+ }
785
+
612
786
  /**
613
787
  * Which fold of text comparison `compareText` and `collationClasses` apply.
614
788
  * Mirrors `fm_collation_strength_t`.
@@ -863,6 +1037,13 @@ export interface SheetFormatDefaults {
863
1037
  baseColWidth: number;
864
1038
  hasDefaultColWidth: boolean;
865
1039
  hasDefaultRowHeight: boolean;
1040
+ /** `<sheetFormatPr customHeight>`: `defaultRowHeight` is an explicit override that stays as
1041
+ * written, rather than a cached figure Excel recomputes from the Normal font. An omitted key
1042
+ * on set keeps the stored flag. */
1043
+ customHeight: boolean;
1044
+ /** `<sheetFormatPr zeroHeight>`: rows are hidden unless they say otherwise. An omitted key
1045
+ * on set keeps the stored flag. */
1046
+ zeroHeight: boolean;
866
1047
  }
867
1048
 
868
1049
  /** Return type of `Workbook.getSheetFormatDefaults(sheet)`. The effective
@@ -963,6 +1144,14 @@ export interface SheetView {
963
1144
  * (A1 for a split) until a host scrolls it. `0, 0` without panes. */
964
1145
  paneTopLeftRow: number;
965
1146
  paneTopLeftCol: number;
1147
+ /** An unfrozen split's position in twips (`<pane xSplit ySplit>`); `0` for no
1148
+ * split on that axis, and always `0` while the view is frozen. */
1149
+ splitX: number;
1150
+ splitY: number;
1151
+ /** `showFormulas`: cells show their formula text; default 0. */
1152
+ showFormulas: number;
1153
+ /** `showOutlineSymbols`: the outline gutter's group symbols are shown; default 1. */
1154
+ showOutlineSymbols: number;
966
1155
  }
967
1156
 
968
1157
  /** The active pane's selection: the active cell and the selected ranges.
@@ -1043,6 +1232,8 @@ export interface ColumnLayout {
1043
1232
  /** Boolean stored as 0/1. */
1044
1233
  hidden: number;
1045
1234
  outlineLevel: number;
1235
+ /** Boolean stored as 0/1: the outline group this span summarises is collapsed. */
1236
+ collapsed: number;
1046
1237
  /** Whether the width is logically explicit (raw presence or non-zero legacy width). */
1047
1238
  hasWidth: number;
1048
1239
  /** Whether the source / model carries an explicit style attribute. */
@@ -1063,6 +1254,8 @@ export interface RowLayout {
1063
1254
  /** Boolean stored as 0/1. */
1064
1255
  hidden: number;
1065
1256
  outlineLevel: number;
1257
+ /** Boolean stored as 0/1: the outline group this row summarises is collapsed. */
1258
+ collapsed: number;
1066
1259
  /** Whether OOXML customFormat=1 makes the row style effective. */
1067
1260
  hasStyle: number;
1068
1261
  styleXf: number;
@@ -1115,6 +1308,45 @@ export interface CommentResult {
1115
1308
  comment: CommentEntry | null;
1116
1309
  }
1117
1310
 
1311
+ /** Workbook-level protection (`<workbookProtection>`). Booleans are stored as 0/1.
1312
+ * Hash fields are stored exactly as given; the host computes them. A zero
1313
+ * spin count and an empty string are absent. */
1314
+ export interface WorkbookProtection {
1315
+ lockStructure: number;
1316
+ lockWindows: number;
1317
+ lockRevision: number;
1318
+ /** Legacy 16-bit password hash, as the hex text Excel writes. */
1319
+ workbookPassword: string;
1320
+ workbookAlgorithmName: string;
1321
+ workbookHashValue: string;
1322
+ workbookSaltValue: string;
1323
+ workbookSpinCount: number;
1324
+ revisionsPassword: string;
1325
+ revisionsAlgorithmName: string;
1326
+ revisionsHashValue: string;
1327
+ revisionsSaltValue: string;
1328
+ revisionsSpinCount: number;
1329
+ }
1330
+
1331
+ /** Return type of `Workbook.getWorkbookProtection()`. */
1332
+ export interface WorkbookProtectionResult {
1333
+ status: Status;
1334
+ protection: WorkbookProtection | null;
1335
+ }
1336
+
1337
+ /** One `<protectedRange>`: a named range users may edit on a protected sheet.
1338
+ * `sqref` is the A1 range list (`"B2:C3 E5"`). */
1339
+ export interface ProtectedRange {
1340
+ name: string;
1341
+ sqref: string;
1342
+ password: string;
1343
+ algorithmName: string;
1344
+ hashValue: string;
1345
+ saltValue: string;
1346
+ spinCount: number;
1347
+ securityDescriptor: string;
1348
+ }
1349
+
1118
1350
  /** Sheet-wide comment entry returned by `getComments(sheet)`. Extends
1119
1351
  * `CommentEntry` with the anchor cell so comments on otherwise-empty
1120
1352
  * cells can be discovered without already knowing their `(row, col)`. */
@@ -1446,9 +1678,21 @@ export interface ConditionalFormatEntry {
1446
1678
  /** Lower bound of the lowest icon's bucket; a cell below it gets no
1447
1679
  * icon. Always present on a rule read back from a workbook. */
1448
1680
  readonly floor?: CfValueObjectInput;
1681
+ /** Custom icon set: the icon drawn for each level, present only when the
1682
+ * set does not draw its own icons. */
1683
+ readonly icons?: ReadonlyArray<CfIconInput>;
1449
1684
  };
1450
1685
  }
1451
1686
 
1687
+ /** One level of a custom icon set. `iconSet` is the `ST_IconSetType` spelling
1688
+ * of the set the icon comes from (`"3Arrows"`, `"3Triangles"`, `"5Boxes"`,
1689
+ * `"NoIcons"` for a level that draws nothing, ...); `iconId` is the
1690
+ * zero-based icon within it. */
1691
+ export interface CfIconInput {
1692
+ iconSet: string;
1693
+ iconId: number;
1694
+ }
1695
+
1452
1696
  /** Argument shape accepted by `addConditionalFormat(sheet, rule)`.
1453
1697
  *
1454
1698
  * When `priority` is missing, zero, or negative, the engine assigns
@@ -1514,6 +1758,9 @@ export interface ConditionalFormatInput {
1514
1758
  /** Lower bound of the lowest icon's bucket; a cell below it gets no
1515
1759
  * icon. Omit for Excel's default, `percent 0`. */
1516
1760
  floor?: CfValueObjectInput;
1761
+ /** Custom icon set: one icon per level (the set's icon count), or omit
1762
+ * for the set's own icons. Evaluation still buckets against `name`. */
1763
+ icons?: ReadonlyArray<CfIconInput>;
1517
1764
  };
1518
1765
  }
1519
1766
 
@@ -1612,6 +1859,16 @@ export interface FontRecord {
1612
1859
  hasItalic: boolean;
1613
1860
  /** Whether the source carried a `<strike>` element at all. */
1614
1861
  hasStrike: boolean;
1862
+ /** `<outline>`, `<shadow>`, `<condense>` and `<extend>` toggles, with the
1863
+ * same `has*` rule as `bold`. */
1864
+ outline: boolean;
1865
+ shadow: boolean;
1866
+ condense: boolean;
1867
+ extend: boolean;
1868
+ hasOutline: boolean;
1869
+ hasShadow: boolean;
1870
+ hasCondense: boolean;
1871
+ hasExtend: boolean;
1615
1872
  /** 0=none, 1=single, 2=double, 3=singleAccounting, 4=doubleAccounting. */
1616
1873
  underline: number;
1617
1874
  /** 0=baseline, 1=superscript, 2=subscript. */
@@ -1649,6 +1906,31 @@ export interface FillRecord {
1649
1906
  fg: ColorSpec;
1650
1907
  /** Original `<bgColor>` specification, preserved for round-tripping. */
1651
1908
  bg: ColorSpec;
1909
+ /** A `<gradientFill>`; when present the pattern fields are ignored. */
1910
+ gradient?: GradientFill;
1911
+ }
1912
+
1913
+ /** A gradient fill. `degree` is a linear gradient's angle; `left` / `right` /
1914
+ * `top` / `bottom` (0..1) locate a path gradient's focus. */
1915
+ export interface GradientFill {
1916
+ /** 0=linear, 1=path. */
1917
+ type: number;
1918
+ degree: number;
1919
+ left: number;
1920
+ right: number;
1921
+ top: number;
1922
+ bottom: number;
1923
+ stops: ReadonlyArray<GradientStop>;
1924
+ }
1925
+
1926
+ /** One stop of a `GradientFill`. */
1927
+ export interface GradientStop {
1928
+ /** 0..1 along the gradient. */
1929
+ position: number;
1930
+ /** AARRGGBB literal RGB or compatibility fallback. */
1931
+ colorArgb: number;
1932
+ /** Original `<color>` specification, preserved for round-tripping. */
1933
+ color: ColorSpec;
1652
1934
  }
1653
1935
 
1654
1936
  /** One side of a `BorderRecord`. */
@@ -2016,6 +2298,48 @@ export enum AnchorEditAs {
2016
2298
  Absolute = 2,
2017
2299
  }
2018
2300
 
2301
+ /** How a shape's fill or outline is specified. Mirrors `fm_shape_paint_t`. */
2302
+ export enum ShapePaint {
2303
+ Unset = 0,
2304
+ Solid = 1,
2305
+ None = 2,
2306
+ Other = 3,
2307
+ }
2308
+
2309
+ /** Table slicer item order. Mirrors `fm_slicer_sort_t`. */
2310
+ export enum SlicerSortOrder {
2311
+ Ascending = 0,
2312
+ Descending = 1,
2313
+ }
2314
+
2315
+ /** How a table slicer shows items other filters exclude. Mirrors `fm_slicer_cross_filter_t`. */
2316
+ export enum SlicerCrossFilter {
2317
+ ShowItemsWithDataAtTop = 0,
2318
+ ShowItemsWithNoData = 1,
2319
+ None = 2,
2320
+ }
2321
+
2322
+ /** Sparkline group type. Mirrors `fm_sparkline_type_t`. */
2323
+ export enum SparklineType {
2324
+ Line = 0,
2325
+ Column = 1,
2326
+ Stacked = 2,
2327
+ }
2328
+
2329
+ /** Sparkline axis scaling. Mirrors `fm_sparkline_axis_type_t`. */
2330
+ export enum SparklineAxisType {
2331
+ Individual = 0,
2332
+ Group = 1,
2333
+ Custom = 2,
2334
+ }
2335
+
2336
+ /** How a sparkline plots empty cells. Mirrors `fm_sparkline_empty_cells_t`. */
2337
+ export enum SparklineEmptyCells {
2338
+ Gap = 0,
2339
+ Zero = 1,
2340
+ Span = 2,
2341
+ }
2342
+
2019
2343
  /** Plot group type. Mirrors `fm_chart_plot_type_t`. */
2020
2344
  export enum ChartPlotType {
2021
2345
  Bar = 0,
@@ -2422,7 +2746,8 @@ export interface AutoFilterEvalResult {
2422
2746
 
2423
2747
  /** Result of `Workbook.validateValue`. `hasRule` is false when no rule covers
2424
2748
  * the cell, and `valid` is then true. Otherwise `ruleIndex` indexes
2425
- * `getValidations` and `errorStyle` is a `ValidationErrorStyle`. */
2749
+ * `getValidations` and `errorStyle` is a `ValidationErrorStyle`. A failed
2750
+ * call reports `hasRule` and `valid` false and the numbers 0. */
2426
2751
  export interface ValidationOutcomeResult {
2427
2752
  status: Status;
2428
2753
  hasRule: boolean;
@@ -2556,6 +2881,205 @@ export interface ImagePlacement {
2556
2881
  heightEmu?: number;
2557
2882
  }
2558
2883
 
2884
+ /** A shape, connector or group of a sheet's drawing. The anchor fields read as in
2885
+ * {@link DrawingObject}. `fillKind` / `lineKind` are {@link ShapePaint}; `fillRgb` /
2886
+ * `lineRgb` are 0xRRGGBB when the kind is `Solid`. `rotation` is in 60000ths of a degree,
2887
+ * `lineWidthEmu` is 0 without a width. `prst` is the preset geometry, empty for custom
2888
+ * geometry or a group; `text` joins paragraphs with `\n`. */
2889
+ export interface Shape {
2890
+ objectId: number;
2891
+ kind: DrawingObjectKind;
2892
+ anchorKind: AnchorKind;
2893
+ editAs: AnchorEditAs;
2894
+ fromRow: number;
2895
+ fromCol: number;
2896
+ fromRowOff: number;
2897
+ fromColOff: number;
2898
+ toRow: number;
2899
+ toCol: number;
2900
+ toRowOff: number;
2901
+ toColOff: number;
2902
+ cx: number;
2903
+ cy: number;
2904
+ name: string;
2905
+ prst: string;
2906
+ text: string;
2907
+ textBox: boolean;
2908
+ fillKind: ShapePaint;
2909
+ fillRgb: number;
2910
+ lineKind: ShapePaint;
2911
+ lineRgb: number;
2912
+ lineWidthEmu: number;
2913
+ rotation: number;
2914
+ hidden: boolean;
2915
+ }
2916
+
2917
+ /** Fields `insertShape` / `updateShape` apply; a key left out (or `null`) is not applied.
2918
+ * Giving `anchorKind` applies the whole anchor (`editAs`, `from*`, `to*`, `cx`, `cy`; a
2919
+ * two-cell anchor's size is its box). `fillKind` / `lineKind` must be `Solid` (with
2920
+ * `fillRgb` / `lineRgb`) or `None`. An insert needs `anchorKind`, defaults `prst` to
2921
+ * `rect` and `name` to `Shape <id>`; a `prst` naming a line or connector geometry makes a
2922
+ * connector, which holds no text. An update cannot change the anchor kind. */
2923
+ export interface ShapeInput {
2924
+ name?: string;
2925
+ prst?: string;
2926
+ text?: string;
2927
+ textBox?: boolean;
2928
+ anchorKind?: AnchorKind;
2929
+ editAs?: AnchorEditAs;
2930
+ fromRow?: number;
2931
+ fromCol?: number;
2932
+ fromRowOff?: number;
2933
+ fromColOff?: number;
2934
+ toRow?: number;
2935
+ toCol?: number;
2936
+ toRowOff?: number;
2937
+ toColOff?: number;
2938
+ cx?: number;
2939
+ cy?: number;
2940
+ fillKind?: ShapePaint;
2941
+ fillRgb?: number;
2942
+ lineKind?: ShapePaint;
2943
+ lineRgb?: number;
2944
+ lineWidthEmu?: number;
2945
+ rotation?: number;
2946
+ hidden?: boolean;
2947
+ }
2948
+
2949
+ /** A table slicer of a worksheet. `objectId` is the slicer's frame in the sheet's drawing (0
2950
+ * without one); the anchor fields read as in {@link DrawingObject}, with `to*` zero unless the
2951
+ * anchor is two-cell. `rowHeight` is in EMU. `cacheName`, `tableName` and `columnName`
2952
+ * identify the slicer cache and the table column it filters; the selection itself lives in the
2953
+ * table's AutoFilter. `style` is empty without a style. */
2954
+ export interface Slicer {
2955
+ objectId: number;
2956
+ name: string;
2957
+ caption: string;
2958
+ cacheName: string;
2959
+ tableName: string;
2960
+ columnName: string;
2961
+ style: string;
2962
+ columnCount: number;
2963
+ rowHeight: number;
2964
+ sortOrder: SlicerSortOrder;
2965
+ crossFilter: SlicerCrossFilter;
2966
+ anchorKind: AnchorKind;
2967
+ fromRow: number;
2968
+ fromCol: number;
2969
+ fromRowOff: number;
2970
+ fromColOff: number;
2971
+ toRow: number;
2972
+ toCol: number;
2973
+ toRowOff: number;
2974
+ toColOff: number;
2975
+ }
2976
+
2977
+ /** Fields `addSlicer` / `updateSlicer` apply; a key left out (or `null`) is not applied.
2978
+ * Giving `fromRow` applies the whole two-cell anchor (`from*`, `to*`). `addSlicer` needs the
2979
+ * anchor and defaults `name` and `caption` to the column name (the name is made unique),
2980
+ * `rowHeight` to 241300 EMU and `columnCount` to 1; `name` cannot be updated. An empty
2981
+ * `style` removes the style. */
2982
+ export interface SlicerInput {
2983
+ name?: string;
2984
+ caption?: string;
2985
+ style?: string;
2986
+ columnCount?: number;
2987
+ rowHeight?: number;
2988
+ fromRow?: number;
2989
+ fromCol?: number;
2990
+ fromRowOff?: number;
2991
+ fromColOff?: number;
2992
+ toRow?: number;
2993
+ toCol?: number;
2994
+ toRowOff?: number;
2995
+ toColOff?: number;
2996
+ sortOrder?: SlicerSortOrder;
2997
+ crossFilter?: SlicerCrossFilter;
2998
+ }
2999
+
3000
+ /** An input cell of a {@link DataTable}. `deleted` is set once a row or column delete removed the cell. */
3001
+ export interface DataTableInput {
3002
+ row: number;
3003
+ col: number;
3004
+ deleted: boolean;
3005
+ }
3006
+
3007
+ /** A What-If data table (`TABLE()`); every coordinate is 0-based and the range inclusive. The row input
3008
+ * cell receives the values of the row above the range and the column input cell those of the column left
3009
+ * of it. A one-variable table has one input (`rowOriented` says which) and the other is `null`; a
3010
+ * two-variable table has both. A deleted input makes the table evaluate to `#REF!`. */
3011
+ export interface DataTable {
3012
+ firstRow: number;
3013
+ lastRow: number;
3014
+ firstCol: number;
3015
+ lastCol: number;
3016
+ twoDimensional: boolean;
3017
+ rowOriented: boolean;
3018
+ rowInput: DataTableInput | null;
3019
+ colInput: DataTableInput | null;
3020
+ }
3021
+
3022
+ /** Argument of `addDataTable`: the result range plus the input cells (`{ row, col }`). Give `rowInput`
3023
+ * or `colInput` for a one-variable table, both for a two-variable one. */
3024
+ export interface DataTableSpec {
3025
+ firstRow: number;
3026
+ lastRow: number;
3027
+ firstCol: number;
3028
+ lastCol: number;
3029
+ rowInput?: { row: number; col: number } | null;
3030
+ colInput?: { row: number; col: number } | null;
3031
+ }
3032
+
3033
+ /** Return type of `Workbook.getDataTable`. `dataTable` is `null` when no table covers the cell. */
3034
+ export interface DataTableResult {
3035
+ status: Status;
3036
+ dataTable: DataTable | null;
3037
+ }
3038
+
3039
+ /** One sparkline: the data `formula` (a sheet-qualified range without `=`) and the
3040
+ * single A1 `location` cell that shows it. */
3041
+ export interface Sparkline {
3042
+ formula: string;
3043
+ location: string;
3044
+ }
3045
+
3046
+ /** A sparkline group of the sheet's worksheet extension list. A colour with `kind` 0 is
3047
+ * absent. `manualMin` / `manualMax` are `null` when the axis bound is not set.
3048
+ * `dateAxisRef` is the group's date range, empty when absent. */
3049
+ export interface SparklineGroup {
3050
+ type: SparklineType;
3051
+ colorSeries: ColorSpec;
3052
+ colorNegative: ColorSpec;
3053
+ colorAxis: ColorSpec;
3054
+ colorMarkers: ColorSpec;
3055
+ colorFirst: ColorSpec;
3056
+ colorLast: ColorSpec;
3057
+ colorHigh: ColorSpec;
3058
+ colorLow: ColorSpec;
3059
+ markers: boolean;
3060
+ high: boolean;
3061
+ low: boolean;
3062
+ first: boolean;
3063
+ last: boolean;
3064
+ negative: boolean;
3065
+ displayXAxis: boolean;
3066
+ displayHidden: boolean;
3067
+ minAxisType: SparklineAxisType;
3068
+ maxAxisType: SparklineAxisType;
3069
+ manualMin: number | null;
3070
+ manualMax: number | null;
3071
+ dateAxis: boolean;
3072
+ dateAxisRef: string;
3073
+ lineWeight: number;
3074
+ emptyCellsAs: SparklineEmptyCells;
3075
+ sparklines: Sparkline[];
3076
+ }
3077
+
3078
+ /** Input of `addSparklineGroup` / `updateSparklineGroup`: every modelled field, each
3079
+ * defaulting as a new line group does when left out. `sparklines` is required by an add and
3080
+ * ignored by an update. */
3081
+ export type SparklineGroupInput = Partial<SparklineGroup>;
3082
+
2559
3083
  /** One series input: nothing, a range reference, or literal points. */
2560
3084
  export interface ChartDataSource {
2561
3085
  kind: 'none' | 'ref' | 'literal';
@@ -3051,7 +3575,12 @@ export interface HeaderFooterInput {
3051
3575
  * status 7003 (`kBindingCallbackException`) instead. Cells committed by
3052
3576
  * the sweeps that already ran keep their values, and the workbook stays
3053
3577
  * usable — the next recalc behaves as if the aborted one had been
3054
- * cancelled deliberately. */
3578
+ * cancelled deliberately.
3579
+ *
3580
+ * The callback runs inside the solver, which holds the workbook mid-sweep:
3581
+ * it must not call any method on the workbook. Such calls, reads included,
3582
+ * throw `TypeError` naming `kGraphRecalcReentrant` (4005) and change
3583
+ * nothing; `delete()` throws `TypeError` as during any other active call. */
3055
3584
  export type IterativeProgressCallback = (
3056
3585
  iteration: number,
3057
3586
  maxResidual: number,
@@ -3081,7 +3610,11 @@ export interface Workbook {
3081
3610
  * contains one of `: \ / ? * [ ]`, or collides case-insensitively (Unicode simple case folding) with an
3082
3611
  * existing sheet, and with `kSheetCountLimitExceeded` at the maximum sheet count. */
3083
3612
  addSheet(name: string): Status;
3084
- /** Removes the sheet at `index`. */
3613
+ /** Removes the sheet at `index`. References to it are rewritten to `#REF!` at the affected subexpression
3614
+ * (cell formulas, defined names, conditional-format, validation and table formulas); sheet-scoped names and
3615
+ * tables owned by the sheet are dropped, as are pivot caches sourced from it and their pivot tables.
3616
+ * Fails with `kSheetIndexOutOfRange`, or `kCannotRemoveLastSheet` when only one sheet remains.
3617
+ * Removing the only visible sheet fails with `kInvalidArgument` and leaves the workbook unchanged. */
3085
3618
  removeSheet(index: number): Status;
3086
3619
  /** Renames the sheet at `index`. */
3087
3620
  renameSheet(index: number, newName: string): Status;
@@ -3248,21 +3781,36 @@ export interface Workbook {
3248
3781
  * `Workbook`: installing one on another instance leaves this one's
3249
3782
  * registration alone.
3250
3783
  *
3251
- * A value that is not callable is accepted here and reported when the
3252
- * solver tries to use it, the same way a throwing callback is. */
3784
+ * A value that is neither a function nor `null` is rejected here with
3785
+ * `kInvalidArgument` (2) and leaves the installed callback in place. */
3253
3786
  setIterativeProgress(callback: IterativeProgressCallback | null): Status;
3254
3787
 
3255
3788
  /**
3256
3789
  * Workbook-level calc mode (Excel `<calcPr calcMode>` policy).
3257
3790
  *
3258
- * `value` is one of the `CalcMode` codes. The engine itself does NOT gate
3259
- * evaluation on this value — every `recalc()` call honours all dirty
3260
- * cells. The mode is preserved as round-trip metadata and surfaced
3261
- * here so the UI can mirror Excel's user-visible state.
3791
+ * `value` is one of the `CalcMode` codes. Apart from `AutoNoTable`, which
3792
+ * makes `recalc()` skip the data tables (see `recalcDataTables`), the
3793
+ * engine does NOT gate evaluation on this value — every `recalc()` call
3794
+ * honours all dirty cells. The mode is round-trip metadata surfaced here
3795
+ * so the UI can mirror Excel's user-visible state.
3262
3796
  */
3263
3797
  calcMode(): NumberResult<CalcMode>;
3264
- /** Sets the calc mode metadata; it does not change evaluation. Returns `kInvalidArgument` for a value outside `CalcMode`. */
3798
+ /** Sets the calc mode; only `AutoNoTable` changes evaluation (`recalc()` skips the data tables). Returns `kInvalidArgument` for a value outside `CalcMode`. */
3265
3799
  setCalcMode(mode: CalcMode): Status;
3800
+ /** `<calcPr fullPrecision>` as 0/1; 0 is "set precision as displayed". Metadata only. */
3801
+ fullPrecision(): NumberResult;
3802
+ setFullPrecision(fullPrecision: boolean): Status;
3803
+ /** `<calcPr calcOnSave>` as 0/1 (default 1). */
3804
+ calcOnSave(): NumberResult;
3805
+ setCalcOnSave(calcOnSave: boolean): Status;
3806
+ /** `<calcPr refMode>` as a `RefMode` code. */
3807
+ refMode(): NumberResult<RefMode>;
3808
+ /** Returns `kInvalidArgument` for a value outside `RefMode`. */
3809
+ setRefMode(mode: RefMode): Status;
3810
+ /** The 1904 date system flag (`<workbookPr date1904>`) as 0/1. */
3811
+ date1904(): NumberResult;
3812
+ /** Switches the date system without converting stored serials, so every date shifts by 1462 days. */
3813
+ setDate1904(date1904: boolean): Status;
3266
3814
 
3267
3815
  /**
3268
3816
  * The workbook's pinned wall-clock reading as `now`, or `now: null` when
@@ -3320,14 +3868,26 @@ export interface Workbook {
3320
3868
  */
3321
3869
 
3322
3870
  /** Inserts `count` rows at `row` on `sheet` and rewrites cross-workbook
3323
- * references to follow the shift. */
3871
+ * references to follow the shift.
3872
+ * Returns `kPreconditionFailed` when the edit cuts into a data table, legacy
3873
+ * array block or PivotTable, or would push one of them or a table past
3874
+ * the sheet bound; the workbook is unchanged. */
3324
3875
  insertRows(sheet: number, row: number, count: number): Status;
3325
3876
  /** Deletes `count` rows starting at `row` on `sheet`. References that
3326
- * fall inside the deleted interval collapse to `#REF!`. */
3877
+ * fall inside the deleted interval collapse to `#REF!`.
3878
+ * Returns `kPreconditionFailed` when the edit cuts into a data table, legacy
3879
+ * array block or PivotTable, or would push one of them or a table past
3880
+ * the sheet bound; the workbook is unchanged. */
3327
3881
  deleteRows(sheet: number, row: number, count: number): Status;
3328
- /** Inserts `count` columns at `col` on `sheet`. */
3882
+ /** Inserts `count` columns at `col` on `sheet`.
3883
+ * Returns `kPreconditionFailed` when the edit cuts into a data table, legacy
3884
+ * array block or PivotTable, or would push one of them or a table past
3885
+ * the sheet bound; the workbook is unchanged. */
3329
3886
  insertCols(sheet: number, col: number, count: number): Status;
3330
- /** Deletes `count` columns starting at `col` on `sheet`. */
3887
+ /** Deletes `count` columns starting at `col` on `sheet`.
3888
+ * Returns `kPreconditionFailed` when the edit cuts into a data table, legacy
3889
+ * array block or PivotTable, or would push one of them or a table past
3890
+ * the sheet bound; the workbook is unchanged. */
3331
3891
  deleteCols(sheet: number, col: number, count: number): Status;
3332
3892
 
3333
3893
  /** Number of written coordinates on `sheet`: cells set by any value, formula or format setter,
@@ -3349,6 +3909,9 @@ export interface Workbook {
3349
3909
  * or a sheet-local scope (0-based sheet index). A non-empty `formula`
3350
3910
  * that does not parse is rejected with `kParserUnexpectedToken`. */
3351
3911
  setDefinedNameScoped(name: string, formula: string, localSheetId: number): Status;
3912
+ /** Sets the `comment` and / or `hidden` of an existing defined name in the given scope;
3913
+ * an omitted key leaves that attribute unchanged. `kInvalidArgument` when no such name exists. */
3914
+ setDefinedNameAttrs(name: string, localSheetId: number, attrs: { comment?: string; hidden?: boolean }): Status;
3352
3915
 
3353
3916
  /** Number of worksheet tables in the workbook. */
3354
3917
  tableCount(): NumberResult;
@@ -3363,6 +3926,12 @@ export interface Workbook {
3363
3926
  updateTable(idx: number, input: TableUpdateInput): Status;
3364
3927
  /** Removes the table at `idx`. */
3365
3928
  removeTable(idx: number): Status;
3929
+ /** Sets column `column`'s totals-row function and label. While the totals
3930
+ * row is shown its cell follows, as the desktop application writes it:
3931
+ * `SUBTOTAL(109,Table[Column])` and the other 1xx codes for a built-in
3932
+ * function, the formula for `'custom'`, else the label as text, else
3933
+ * nothing. */
3934
+ setTableColumnTotals(idx: number, column: number, totals: TableColumnTotalsInput): Status;
3366
3935
 
3367
3936
  /** Reads the complete worksheet-level `<autoFilter>` XML fragment. */
3368
3937
  getSheetAutoFilterXml(sheet: number): SheetAutoFilterXmlResult;
@@ -3443,6 +4012,48 @@ export interface Workbook {
3443
4012
  /** 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`. */
3444
4013
  restoreDrawing(sheet: number, bytes: Uint8Array, opts?: RestoreImageOptions): InsertImageResult;
3445
4014
 
4015
+ // Drawing shapes. A shape is addressed as `(sheet, objectId)`, the id `listShapes` reports.
4016
+ /** Lists the shapes, connectors and groups of the sheet's drawing in z-order (back first); children of a group are not listed. */
4017
+ listShapes(sheet: number): ListResult<Shape>;
4018
+ /** Appends a shape on top and returns its id; a sheet without a drawing gets one and existing drawing content is kept. */
4019
+ insertShape(sheet: number, spec: ShapeInput): InsertImageResult;
4020
+ /** Applies the fields `spec` names to the shape `objectId`; every other part of its XML is kept. */
4021
+ updateShape(sheet: number, objectId: number, spec: ShapeInput): Status;
4022
+ /** Removes the shape, connector or group `objectId` with its children. */
4023
+ removeShape(sheet: number, objectId: number): Status;
4024
+
4025
+ // Table slicers. A slicer is addressed by its position in `listSlicers`; adding or removing one shifts later indices.
4026
+ /** Lists the table slicers the sheet hosts; slicers over a pivot cache are not listed. */
4027
+ listSlicers(sheet: number): ListResult<Slicer>;
4028
+ /** Adds a slicer over column `column` (0-based) of table `table` and returns its frame's id. It creates the slicer and cache parts, the `Slicer_*` defined name and the drawing frame; the table may live on another sheet. */
4029
+ addSlicer(sheet: number, table: number, column: number, spec: SlicerInput): InsertImageResult;
4030
+ /** Applies the fields `spec` names to slicer `index`; every other part of its XML is kept. */
4031
+ updateSlicer(sheet: number, index: number, spec: SlicerInput): Status;
4032
+ /** Removes slicer `index` with its drawing frame, and its cache when no other slicer uses it. Removing a table or sheet removes the slicers bound to it. */
4033
+ removeSlicer(sheet: number, index: number): Status;
4034
+
4035
+ // What-If data tables. The formulas sit in the row above the result range and the substitution values in the column left of it (or the other way round); each result cell is found by substituting into the input cell(s), recalculating the cells that read them and restoring the inputs.
4036
+ /** Creates a data table over `spec`'s result range. The result cells read 0 until the next recalc and refuse writes ("cannot change part of a data table") until the table is removed. `kDataTableInvalid` (8005) when no input is given, the range has no row above or column left of it, an input lies inside the range, or the range overlaps another data table. */
4037
+ addDataTable(sheet: number, spec: DataTableSpec): Status;
4038
+ /** Reads the data table whose result range contains `(row, col)`. */
4039
+ getDataTable(sheet: number, row: number, col: number): DataTableResult;
4040
+ /** Removes the data table containing `(row, col)` and blanks its result cells. `kDataTableInvalid` (8005) when none covers the cell. */
4041
+ removeDataTable(sheet: number, row: number, col: number): Status;
4042
+ /** Recomputes every data table now, whatever the calc mode. `recalc()` does the same after a pass that had a dirty cell or a volatile formula, except under `CalcMode.AutoNoTable`, which leaves it to this call; `partialRecalc()` never computes tables. */
4043
+ recalcDataTables(): Status;
4044
+
4045
+ // Sparkline groups. A group is addressed by its position in `listSparklineGroups`; adding or removing one shifts later indices.
4046
+ /** Lists the sheet's sparkline groups in document order with their sparklines. */
4047
+ listSparklineGroups(sheet: number): ListResult<SparklineGroup>;
4048
+ /** Appends a group; `spec.sparklines` must hold at least one sparkline. */
4049
+ addSparklineGroup(sheet: number, spec: SparklineGroupInput): Status;
4050
+ /** Rewrites the modelled attributes, colours and date range of group `index`; its sparklines and unmodelled XML are kept. */
4051
+ updateSparklineGroup(sheet: number, index: number, spec: SparklineGroupInput): Status;
4052
+ /** Replaces the sparklines of group `index`. */
4053
+ setSparklineGroupSparklines(sheet: number, index: number, sparklines: Sparkline[]): Status;
4054
+ /** Removes group `index`. */
4055
+ removeSparklineGroup(sheet: number, index: number): Status;
4056
+
3446
4057
  // Charts. A chart is addressed as `(sheet, objectId)`, the id `listDrawingObjects` reports for a `DrawingObjectKind.Chart`.
3447
4058
  /** Reads the typed view of the chart `objectId`. */
3448
4059
  getChart(sheet: number, objectId: number): ChartResult;
@@ -3588,6 +4199,10 @@ export interface Workbook {
3588
4199
  ): Status;
3589
4200
  /** Toggles the row / column grand total bands on the pivot. */
3590
4201
  pivotSetGrandTotals(sheet: number, pivotIdx: number, rowsEnabled: boolean, colsEnabled: boolean): Status;
4202
+ /** Sets the pivot's table style and toggles, making the style element
4203
+ * present. New pivots start as `PivotStyleLight16` with row / column
4204
+ * headers and last column on. */
4205
+ pivotSetStyleInfo(sheet: number, pivotIdx: number, info: PivotStyleInfo): Status;
3591
4206
  /** Reads the pivot's compact / tabular / outline report layout. */
3592
4207
  pivotGetLayout(sheet: number, pivotIdx: number): PivotReportLayoutResult;
3593
4208
  /** Sets the pivot's compact / tabular / outline report layout. */
@@ -3600,6 +4215,8 @@ export interface Workbook {
3600
4215
  pivotName(sheet: number, pivotIdx: number): StringResult;
3601
4216
  /** Reads the row / column grand total flags `pivotSetGrandTotals` writes. */
3602
4217
  pivotGetGrandTotals(sheet: number, pivotIdx: number): PivotGrandTotalsResult;
4218
+ /** Reads the table style `pivotSetStyleInfo` writes. */
4219
+ pivotGetStyleInfo(sheet: number, pivotIdx: number): PivotStyleInfoResult;
3603
4220
  /** Reads the row-axis field order (the list `pivotSetRowFieldOrder` takes). */
3604
4221
  pivotRowFieldOrder(sheet: number, pivotIdx: number): PivotFieldOrderResult;
3605
4222
  /** Reads the column-axis field order. */
@@ -3607,8 +4224,14 @@ export interface Workbook {
3607
4224
 
3608
4225
  /** Number of fields configured on the pivot. */
3609
4226
  pivotFieldCount(sheet: number, pivotIdx: number): NumberResult;
3610
- /** Appends a new field. Returns `{ status, index: fieldIdx }`. A field
3611
- * added on the row or column axis is appended to that axis's order. */
4227
+ /** Places a field on the pivot. Returns `{ status, index: fieldIdx }`.
4228
+ * A pivot's fields are positional over its cache's fields (field `i` is
4229
+ * cache field `i`): when `sourceName` names a cache field the pivot first
4230
+ * gets one bare, axis-less field per cache field and the named one is
4231
+ * configured in place, so `index` is that cache field's position and
4232
+ * adding it again updates it. A name the cache lacks appends a field.
4233
+ * A field added on the row or column axis is appended to that axis's
4234
+ * order. */
3612
4235
  pivotFieldAdd(sheet: number, pivotIdx: number, spec: PivotFieldSpec): AddStyleResult;
3613
4236
  /** Reads the definition of field `fieldIdx`. */
3614
4237
  pivotFieldAt(sheet: number, pivotIdx: number, fieldIdx: number): PivotFieldResult;
@@ -3621,8 +4244,12 @@ export interface Workbook {
3621
4244
  /** Drops every field from the pivot, emptying the row and column orders. */
3622
4245
  pivotFieldClear(sheet: number, pivotIdx: number): Status;
3623
4246
  /** Sets the axis of pivot field `fieldIdx`. Moving onto the row or column
3624
- * axis appends the field to that axis's order; moving off removes it. */
3625
- pivotFieldSetAxis(sheet: number, pivotIdx: number, fieldIdx: number, axis: PivotAxis): Status;
4247
+ * axis appends the field to that axis's order; moving off removes it.
4248
+ * `-1` takes the field off every axis, as unchecking it in a field list
4249
+ * does: its data fields are removed (later data-field indices shift
4250
+ * down), as are filters naming it and value filters scoring a
4251
+ * removed data field; its item visibility is kept. */
4252
+ pivotFieldSetAxis(sheet: number, pivotIdx: number, fieldIdx: number, axis: PivotAxis | -1): Status;
3626
4253
  /** Sets the sibling order of pivot field `fieldIdx`. `PivotSortOrder.Manual`
3627
4254
  * keeps items in `pivotFieldAddItem` order and takes no `byField`; for the
3628
4255
  * other orders an empty `byField` sorts by label. */
@@ -3661,13 +4288,14 @@ export interface Workbook {
3661
4288
  /** Configures date-grouping on pivot field `fieldIdx`. Pass `-1` for
3662
4289
  * `startYear` / `endYear` to leave the Year-truncation bound unset
3663
4290
  * (meaningful only for `PivotDateGrouping.Year`). `intervalDays` is
3664
- * the `PivotDateGrouping.Days`-only bucket width in whole days; pass
3665
- * `1` for every other granularity. `startSerial` / `endSerial` are
3666
- * the `Days`-only Start/End window as Excel date serials -- pass
3667
- * `-1` for either to leave it auto (Start = the field's data
3668
- * minimum, End = the data maximum plus one day); ignored otherwise.
3669
- * With `Days`, a zero `intervalDays` or a start after the end is
3670
- * rejected with `kInvalidArgument`. */
4291
+ * the `PivotDateGrouping.Days`-only bucket width in whole days;
4292
+ * defaults to `1`, which is also what every other granularity
4293
+ * should pass. `startSerial` / `endSerial` are the `Days`-only
4294
+ * Start/End window as Excel date serials; default `-1` leaves
4295
+ * either auto (Start = the field's data minimum, End = the data
4296
+ * maximum plus one day), and both are ignored for every other
4297
+ * granularity. With `Days`, a zero `intervalDays` or a start after
4298
+ * the end is rejected with `kInvalidArgument`. */
3671
4299
  pivotFieldSetDateGroup(
3672
4300
  sheet: number,
3673
4301
  pivotIdx: number,
@@ -3676,9 +4304,9 @@ export interface Workbook {
3676
4304
  calendar: PivotCalendar,
3677
4305
  startYear: number,
3678
4306
  endYear: number,
3679
- intervalDays: number,
3680
- startSerial: number,
3681
- endSerial: number,
4307
+ intervalDays?: number,
4308
+ startSerial?: number,
4309
+ endSerial?: number,
3682
4310
  ): Status;
3683
4311
  /** Removes the date-grouping config from pivot field `fieldIdx`. */
3684
4312
  pivotFieldClearDateGroup(sheet: number, pivotIdx: number, fieldIdx: number): Status;
@@ -3708,18 +4336,15 @@ export interface Workbook {
3708
4336
  * or empty `spec.name` is derived as in `pivotDataFieldAdd`. */
3709
4337
  pivotDataFieldSet(sheet: number, pivotIdx: number, dataFieldIdx: number, spec: PivotDataFieldSpec): Status;
3710
4338
 
3711
- /** Number of active (slicer-applied) filters on the pivot. Counts only
3712
- * the entries this session added -- see {@link PivotFilterResult}. */
4339
+ /** Number of filters on the pivot -- see {@link PivotFilterResult}. */
3713
4340
  pivotFilterCount(sheet: number, pivotIdx: number): NumberResult;
3714
- /** Appends an active filter. The entry is session state and is not
3715
- * written by `save`; see {@link PivotFilterResult}. */
4341
+ /** Appends a filter, saved with the pivot; see {@link PivotFilterResult}. */
3716
4342
  pivotFilterAdd(sheet: number, pivotIdx: number, spec: PivotFilterSpec): Status;
3717
- /** Reads the active filter at `filterIdx`. The list is session state:
3718
- * see {@link PivotFilterResult}. */
4343
+ /** Reads the filter at `filterIdx`; see {@link PivotFilterResult}. */
3719
4344
  pivotFilterAt(sheet: number, pivotIdx: number, filterIdx: number): PivotFilterResult;
3720
- /** Drops every active filter from the pivot. */
4345
+ /** Drops every listed filter from the pivot. */
3721
4346
  pivotFilterClear(sheet: number, pivotIdx: number): Status;
3722
- /** Removes the active filter at `filterIdx`. */
4347
+ /** Removes the filter at `filterIdx`. */
3723
4348
  pivotFilterRemoveAt(sheet: number, pivotIdx: number, filterIdx: number): Status;
3724
4349
 
3725
4350
  /** Evaluates every CF block on `sheet` against the inclusive range
@@ -3818,13 +4443,15 @@ export interface Workbook {
3818
4443
  * `setSheetVisibility`. `true` on an already very-hidden sheet leaves
3819
4444
  * it very-hidden rather than demoting it, since "hidden" says nothing
3820
4445
  * that sheet does not already satisfy; `false` shows it from either
3821
- * hidden state. */
4446
+ * hidden state. Hiding the only visible sheet fails with
4447
+ * `kInvalidArgument` and leaves it visible. */
3822
4448
  setSheetTabHidden(sheet: number, hidden: boolean): Status;
3823
4449
  /** Sets the sheet tab's visibility to one of the three states. The only
3824
4450
  * way to newly state `SheetVisibility.VeryHidden`, and the only way to
3825
4451
  * demote a very-hidden sheet to plain hidden; `setSheetTabHidden` can
3826
4452
  * express neither. A value outside `SheetVisibility` fails with
3827
- * `kInvalidArgument` and leaves the sheet unchanged. */
4453
+ * `kInvalidArgument` and leaves the sheet unchanged. So does hiding the only
4454
+ * visible sheet. */
3828
4455
  setSheetVisibility(sheet: number, visibility: SheetVisibility): Status;
3829
4456
  /** Sets the sheet's `showGridLines` flag. */
3830
4457
  setSheetShowGridLines(sheet: number, show: boolean): Status;
@@ -3832,6 +4459,10 @@ export interface Workbook {
3832
4459
  setSheetShowRowColHeaders(sheet: number, show: boolean): Status;
3833
4460
  /** Sets the sheet's `showZeros` flag. */
3834
4461
  setSheetShowZeros(sheet: number, show: boolean): Status;
4462
+ /** Sets the sheet's `showFormulas` flag. */
4463
+ setSheetShowFormulas(sheet: number, show: boolean): Status;
4464
+ /** Sets the sheet's `showOutlineSymbols` flag. */
4465
+ setSheetShowOutlineSymbols(sheet: number, show: boolean): Status;
3835
4466
  /** Sets the sheet's `rightToLeft` flag. */
3836
4467
  setSheetRightToLeft(sheet: number, rightToLeft: boolean): Status;
3837
4468
  /** Sets the sheet's `tabSelected` flag. */
@@ -3842,6 +4473,11 @@ export interface Workbook {
3842
4473
  * pane. It must lie past any frozen rows and columns; rejected without
3843
4474
  * panes. Changing the freeze resets it to the first unfrozen cell. */
3844
4475
  setSheetPaneTopLeft(sheet: number, row: number, col: number): Status;
4476
+ /** Splits the view at `xTwips` / `yTwips` (`0` for none on that axis;
4477
+ * `0, 0` removes the split). Replaces any freeze, as `setSheetFreeze`
4478
+ * replaces a split. Negative or non-finite values fail with
4479
+ * `kInvalidArgument` and leave the view unchanged. */
4480
+ setSheetSplit(sheet: number, xTwips: number, yTwips: number): Status;
3845
4481
  /** Reads the active pane's selection (active cell and ranges). */
3846
4482
  getSheetSelection(sheet: number): SheetSelectionResult;
3847
4483
  /** Replaces the active pane's selection. In a frozen or split view the
@@ -3871,8 +4507,11 @@ export interface Workbook {
3871
4507
  setColumnWidth(sheet: number, first: number, last: number, width: number): Status;
3872
4508
  /** Sets / replaces the column hidden flag on `[first, last]`. */
3873
4509
  setColumnHidden(sheet: number, first: number, last: number, hidden: boolean): Status;
3874
- /** Sets / replaces the column outline level on `[first, last]` (clamped to 0..255). */
4510
+ /** Sets / replaces the column outline level on `[first, last]`. A level
4511
+ * above 7, the deepest Excel stores, fails with `kInvalidArgument`. */
3875
4512
  setColumnOutline(sheet: number, first: number, last: number, level: number): Status;
4513
+ /** Sets / clears the column `collapsed` flag on `[first, last]`. */
4514
+ setColumnCollapsed(sheet: number, first: number, last: number, collapsed: boolean): Status;
3876
4515
  /** Sets / replaces the cell-style XF on `[first, last]`; index 0 is the default XF. A value later entered into an unstyled cell of the span takes this XF, unless its row has a style. */
3877
4516
  setColumnStyle(sheet: number, first: number, last: number, xfIndex: number): Status;
3878
4517
  /** Removes the cell-style XF on `[first, last]`, retaining other column attributes. */
@@ -3884,8 +4523,11 @@ export interface Workbook {
3884
4523
  setRowHeight(sheet: number, row: number, height: number): Status;
3885
4524
  /** Sets / replaces the row hidden flag at `row`. */
3886
4525
  setRowHidden(sheet: number, row: number, hidden: boolean): Status;
3887
- /** Sets / replaces the row outline level at `row` (clamped to 0..255). */
4526
+ /** Sets / replaces the row outline level at `row`. A level above 7, the
4527
+ * deepest Excel stores, fails with `kInvalidArgument`. */
3888
4528
  setRowOutline(sheet: number, row: number, level: number): Status;
4529
+ /** Sets / clears the row `collapsed` flag at `row`. */
4530
+ setRowCollapsed(sheet: number, row: number, collapsed: boolean): Status;
3889
4531
  /** Sets / replaces the cell-style XF of the inclusive row span `first..last`; index 0 is the default XF. A value later entered into an unstyled cell of a covered row takes this XF. Nothing changes on failure. */
3890
4532
  setRowStyle(sheet: number, first: number, last: number, xfIndex: number): Status;
3891
4533
  /** Removes the cell-style XF of the inclusive row span `first..last`, retaining other row attributes. */
@@ -3962,7 +4604,8 @@ export interface Workbook {
3962
4604
 
3963
4605
  /** Returns `{ status, xfIndex }` for the cell at `(sheet, row, col)`. */
3964
4606
  getCellXfIndex(sheet: number, row: number, col: number): CellXfIndexResult;
3965
- /** Persists `xfIndex` on the cell at `(sheet, row, col)`. */
4607
+ /** Persists `xfIndex` on the cell at `(sheet, row, col)`. An index not
4608
+ * below `xfCount()` fails with `kInvalidArgument`. */
3966
4609
  setCellXfIndex(sheet: number, row: number, col: number, xfIndex: number): Status;
3967
4610
  /**
3968
4611
  * Removes the direct style assignment from the cell at `(sheet, row, col)`
@@ -3974,7 +4617,8 @@ export interface Workbook {
3974
4617
  */
3975
4618
  clearCellXfIndex(sheet: number, row: number, col: number): Status;
3976
4619
  /** Applies `xfIndex` across an inclusive rectangle, materialising blank
3977
- * cells so an empty ruled box renders. Saves one call per cell. */
4620
+ * cells so an empty ruled box renders. Saves one call per cell. An
4621
+ * index not below `xfCount()` fails with `kInvalidArgument`. */
3978
4622
  setRangeXfIndex(
3979
4623
  sheet: number,
3980
4624
  firstRow: number,
@@ -3983,7 +4627,8 @@ export interface Workbook {
3983
4627
  lastCol: number,
3984
4628
  xfIndex: number,
3985
4629
  ): Status;
3986
- /** Returns the resolved XF record at `xfIndex`. */
4630
+ /** Returns the resolved XF record at `xfIndex`. A failed read reports
4631
+ * the all-default record (`locked` true, every other flag false). */
3987
4632
  getCellXf(xfIndex: number): CellXfResult;
3988
4633
  /** Returns the font record at `fontIndex`, including its ColorSpec selector. */
3989
4634
  getFont(fontIndex: number): FontResult;
@@ -4066,6 +4711,25 @@ export interface Workbook {
4066
4711
  * repointed at the Normal style. */
4067
4712
  removeCellStyle(name: string): Status;
4068
4713
 
4714
+ /** Number of custom table / PivotTable styles (`<tableStyles>`). */
4715
+ tableStyleCount(): NumberResult;
4716
+ /** Reads the custom table style at `index`. */
4717
+ getTableStyle(index: number): TableStyleResult;
4718
+ /** Adds a custom table style, or replaces the one with the same name
4719
+ * (case-insensitive). The name may not be a built-in style name; each
4720
+ * element type may appear once, `size` must be at least 1 and `dxfId`
4721
+ * must name an existing differential format. A first style also sets the
4722
+ * defaults to `TableStyleMedium2` / `PivotStyleLight16`. */
4723
+ setTableStyle(style: TableStyle): Status;
4724
+ /** Removes the custom table style `name`. A default naming it reverts to
4725
+ * the built-in default; tables and pivots naming it keep the name. */
4726
+ removeTableStyle(name: string): Status;
4727
+ /** Reads the default table and PivotTable style names. */
4728
+ getTableStyleDefaults(): TableStyleDefaultsResult;
4729
+ /** Sets the default style names; an omitted field keeps its default and an
4730
+ * empty string removes it. */
4731
+ setTableStyleDefaults(defaults: { tableStyle?: string; pivotStyle?: string }): Status;
4732
+
4069
4733
  /** The 12 theme colours (`clrScheme` order) and the theme typefaces. The
4070
4734
  * default theme is reported when the part is absent or unparseable;
4071
4735
  * `source` tells the cases apart. */
@@ -4121,6 +4785,23 @@ export interface Workbook {
4121
4785
  getComments(sheet: number): ListResult<SheetCommentEntry>;
4122
4786
  /** Sets / replaces the cell comment. Pass an empty `text` to remove. */
4123
4787
  setComment(sheet: number, row: number, col: number, author: string, text: string): Status;
4788
+ /** Whether the note at `(sheet, row, col)` is shown without hovering (`value` 0 or 1). */
4789
+ getCommentVisible(sheet: number, row: number, col: number): NumberResult;
4790
+ /** Shows or hides the note at `(sheet, row, col)`; its box geometry is kept. */
4791
+ setCommentVisible(sheet: number, row: number, col: number, visible: boolean): Status;
4792
+
4793
+ /** Reads the workbook's `<workbookProtection>`; every field is zero or empty when absent. */
4794
+ getWorkbookProtection(): WorkbookProtectionResult;
4795
+ /** Replaces the modelled `<workbookProtection>` attributes. An all-empty record removes the element. */
4796
+ setWorkbookProtection(protection: WorkbookProtection): Status;
4797
+ /** Returns the protected ranges of `sheet` in file order. */
4798
+ getProtectedRanges(sheet: number): ListResult<ProtectedRange>;
4799
+ /** Appends a protected range. `name` must be non-empty and unique on the sheet; `sqref` must parse as A1 ranges. */
4800
+ addProtectedRange(sheet: number, range: ProtectedRange): Status;
4801
+ /** Replaces protected range `index`. */
4802
+ updateProtectedRange(sheet: number, index: number, range: ProtectedRange): Status;
4803
+ /** Removes protected range `index`. */
4804
+ removeProtectedRange(sheet: number, index: number): Status;
4124
4805
 
4125
4806
  /** Appends a hyperlink to `sheet`. For an in-workbook link, pass an empty
4126
4807
  * `target` and its A1 destination as `location`. */
@@ -4345,7 +5026,9 @@ export interface FormulonModule {
4345
5026
  *
4346
5027
  * A sink that throws has its exception dropped and the record lost;
4347
5028
  * the call that emitted it is unaffected. Records come from arbitrary
4348
- * depth inside the engine, so there is nowhere to report it. */
5029
+ * depth inside the engine, so there is nowhere to report it. A value
5030
+ * that is neither a function nor `null` is rejected with
5031
+ * `kInvalidArgument` (2) and leaves the installed sink in place. */
4349
5032
  setLogSink(sink: ((record: Uint8Array) => void) | null): Status;
4350
5033
  }
4351
5034