@libraz/formulon 0.16.1 → 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;
212
+ }
213
+
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;
203
234
  }
204
235
 
205
- /** Return type of `Workbook.tableAt(idx)`. */
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;
@@ -438,7 +575,11 @@ export interface PivotFieldSpec {
438
575
  * `pivotDataFieldSet`. Mirrors `fm_pivot_data_field_spec_t`. Pass
439
576
  * `-1` for `showAsBaseField` / `showAsBaseItem` to mean "unset". */
440
577
  export interface PivotDataFieldSpec {
441
- name: string;
578
+ /** Display name (key for GETPIVOTDATA). Omit or pass `""` to let the
579
+ * engine name the data field from the workbook profile's pivot wording,
580
+ * e.g. `"Sum of Sales"` (en-US) or `"合計 / Sales"` (ja-JP). That needs
581
+ * `fieldIndex` to be in range. */
582
+ name?: string;
442
583
  fieldIndex: number;
443
584
  aggregation: PivotAggregation;
444
585
  /** `numFmtId` as a decimal string (built-in or from `addNumFmt`). */
@@ -448,6 +589,105 @@ export interface PivotDataFieldSpec {
448
589
  showAsBaseItem?: number;
449
590
  }
450
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
+
617
+ /** Return type of `Workbook.pivotGetGrandTotals(...)`. */
618
+ export interface PivotGrandTotalsResult {
619
+ status: Status;
620
+ rows: boolean;
621
+ cols: boolean;
622
+ }
623
+
624
+ /** Return type of `Workbook.pivotRowFieldOrder` / `pivotColFieldOrder`:
625
+ * the indices `pivotSetRowFieldOrder` / `pivotSetColFieldOrder` take. */
626
+ export interface PivotFieldOrderResult {
627
+ status: Status;
628
+ indices: number[];
629
+ }
630
+
631
+ /** Return type of `Workbook.pivotFieldAt(...)`. `sourceName`, `customName`,
632
+ * `axis`, `subtotalTop` and `numberFormat` match `PivotFieldSpec`, except
633
+ * that `axis` is `-1` for a field that sits on no axis. */
634
+ export interface PivotFieldResult {
635
+ status: Status;
636
+ sourceName: string;
637
+ customName: string;
638
+ axis: PivotAxis | -1;
639
+ subtotalTop: boolean;
640
+ numberFormat: string;
641
+ /** Index of the bound pivot-cache field, `-1` when the cache does not
642
+ * cover this field. Pivot field `i` binds to cache field `i`. */
643
+ cacheFieldIndex: number;
644
+ /** As written by `pivotFieldSetSort`. */
645
+ sortOrder: PivotSortOrder;
646
+ sortByField: string;
647
+ /** When `false` the `date*` members are zero and the unset sentinels. */
648
+ hasDateGroup: boolean;
649
+ dateGranularity: PivotDateGrouping;
650
+ dateCalendar: PivotCalendar;
651
+ /** `-1` when unset. */
652
+ dateStartYear: number;
653
+ dateEndYear: number;
654
+ dateIntervalDays: number;
655
+ /** `-1` when unset. */
656
+ dateStartSerial: number;
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[];
664
+ }
665
+
666
+ /** Return type of `Workbook.pivotFieldItemAt(...)`. */
667
+ export interface PivotItemResult {
668
+ status: Status;
669
+ /** The item's own label; empty for an item bound only by cache index. */
670
+ name: string;
671
+ /** Index into the bound cache field's shared items, `-1` for an item
672
+ * bound by label only. */
673
+ cacheIndex: number;
674
+ visible: boolean;
675
+ }
676
+
677
+ /** Return type of `Workbook.pivotDataFieldAt(...)`. Same shape as
678
+ * `PivotDataFieldSpec` with every member present; `showAsBaseField` /
679
+ * `showAsBaseItem` are `-1` when unset and `numberFormat` is `""` for none. */
680
+ export interface PivotDataFieldResult {
681
+ status: Status;
682
+ name: string;
683
+ fieldIndex: number;
684
+ aggregation: PivotAggregation;
685
+ numberFormat: string;
686
+ showAs: PivotShowValuesAs;
687
+ showAsBaseField: number;
688
+ showAsBaseItem: number;
689
+ }
690
+
451
691
  /** Plain-data spec for `Workbook.pivotFilterAdd`. Mirrors
452
692
  * `fm_pivot_filter_spec_t`. For non-range filters, `valueKind` must be
453
693
  * one of `Int` / `Double` / `Text`; the high-bound payload is honoured
@@ -470,12 +710,11 @@ export interface PivotFilterSpec {
470
710
  /** Return type of `Workbook.pivotFilterAt(...)`: the stored filter plus a
471
711
  * status envelope. Field names and semantics match `PivotFilterSpec`.
472
712
  *
473
- * The active-filter list is **session state**. An entry added through
474
- * `pivotFilterAdd` affects evaluation only while the workbook handle
475
- * lives and is not written by `save`. Conversely a `<filters>` block
476
- * Excel wrote is preserved verbatim on save but does not appear here, so
477
- * `pivotFilterCount` reports only what this session added. The filter
478
- * 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. */
479
718
  export interface PivotFilterResult {
480
719
  status: Status;
481
720
  axis: number;
@@ -526,10 +765,11 @@ export enum ErrorCode {
526
765
  *
527
766
  * - `Auto` — recalc on every input change (Excel default).
528
767
  * - `Manual` — only recalc when explicitly requested.
529
- * - `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.
530
770
  *
531
- * Round-trip metadata only — the engine recalcs all dirty cells
532
- * 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.
533
773
  */
534
774
  export enum CalcMode {
535
775
  Auto = 0,
@@ -537,6 +777,12 @@ export enum CalcMode {
537
777
  AutoNoTable = 2,
538
778
  }
539
779
 
780
+ /** Reference notation formulas are shown in (`<calcPr refMode>`). */
781
+ export enum RefMode {
782
+ A1 = 0,
783
+ R1C1 = 1,
784
+ }
785
+
540
786
  /**
541
787
  * Which fold of text comparison `compareText` and `collationClasses` apply.
542
788
  * Mirrors `fm_collation_strength_t`.
@@ -767,7 +1013,8 @@ export interface CellRectResult extends RectPt {
767
1013
  status: Status;
768
1014
  }
769
1015
 
770
- /** Return type of `Workbook.getWidthModel(...)`. */
1016
+ /** Return type of `Workbook.getWidthModel(...)`. `pointsPerChar` and `paddingPt` are per displayed
1017
+ * character: `chars * pointsPerChar + paddingPt`; stored widths go through `columnCharsToPt`. */
771
1018
  export interface WidthModelResult {
772
1019
  status: Status;
773
1020
  pointsPerChar: number;
@@ -790,13 +1037,21 @@ export interface SheetFormatDefaults {
790
1037
  baseColWidth: number;
791
1038
  hasDefaultColWidth: boolean;
792
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;
793
1047
  }
794
1048
 
795
1049
  /** Return type of `Workbook.getSheetFormatDefaults(sheet)`. The effective
796
1050
  * values are read-only and ignored by `setSheetFormatDefaults`. */
797
1051
  export interface SheetFormatDefaultsResult extends SheetFormatDefaults {
798
1052
  status: Status;
799
- /** Character units the sheet lays columns out with: `defaultColWidth` when set, else 8.43. */
1053
+ /** Stored width the sheet lays columns out with: `defaultColWidth` when set, else the column
1054
+ * Excel derives from `baseColWidth` and the Normal font (Calibri 11, base 8: 9.140625, shown as 8.43). */
800
1055
  effectiveDefaultColWidth: number;
801
1056
  /** Points the sheet lays rows out with: `defaultRowHeight` when set, else 102/7 (about 14.57); 0 when `zeroHeight` hides rows by default. */
802
1057
  effectiveDefaultRowHeight: number;
@@ -881,6 +1136,42 @@ export interface SheetView {
881
1136
  tabSelected: number;
882
1137
  /** `view` mode: `""` (normal), `"pageBreakPreview"`, or `"pageLayout"`. */
883
1138
  viewMode: string;
1139
+ /** Scroll origin of the sheet view (`topLeftCell`), 0-based; A1 by default. */
1140
+ topLeftRow: number;
1141
+ topLeftCol: number;
1142
+ /** First visible cell of a frozen or split view's lower-right pane
1143
+ * (`<pane topLeftCell>`): the first cell past the frozen rows and columns
1144
+ * (A1 for a split) until a host scrolls it. `0, 0` without panes. */
1145
+ paneTopLeftRow: number;
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;
1155
+ }
1156
+
1157
+ /** The active pane's selection: the active cell and the selected ranges.
1158
+ * Input of `Workbook.setSheetSelection`; `ranges` may be empty or omitted,
1159
+ * which selects the active cell alone. */
1160
+ export interface SheetSelection {
1161
+ activeRow: number;
1162
+ activeCol: number;
1163
+ ranges?: ReadonlyArray<MergeRange>;
1164
+ }
1165
+
1166
+ /** Return type of `Workbook.getSheetSelection(sheet)`, read as it is saved:
1167
+ * a pane that stores no selection reports A1 with the single range A1 (the
1168
+ * pane's top-left cell for a frozen or split view's active pane), and an
1169
+ * active cell outside every range moves to the first range's top-left. */
1170
+ export interface SheetSelectionResult {
1171
+ status: Status;
1172
+ activeRow: number;
1173
+ activeCol: number;
1174
+ ranges: MergeRange[];
884
1175
  }
885
1176
 
886
1177
  /** Return type of `Workbook.getSheetView(sheet)`. */
@@ -941,6 +1232,8 @@ export interface ColumnLayout {
941
1232
  /** Boolean stored as 0/1. */
942
1233
  hidden: number;
943
1234
  outlineLevel: number;
1235
+ /** Boolean stored as 0/1: the outline group this span summarises is collapsed. */
1236
+ collapsed: number;
944
1237
  /** Whether the width is logically explicit (raw presence or non-zero legacy width). */
945
1238
  hasWidth: number;
946
1239
  /** Whether the source / model carries an explicit style attribute. */
@@ -961,6 +1254,8 @@ export interface RowLayout {
961
1254
  /** Boolean stored as 0/1. */
962
1255
  hidden: number;
963
1256
  outlineLevel: number;
1257
+ /** Boolean stored as 0/1: the outline group this row summarises is collapsed. */
1258
+ collapsed: number;
964
1259
  /** Whether OOXML customFormat=1 makes the row style effective. */
965
1260
  hasStyle: number;
966
1261
  styleXf: number;
@@ -1013,6 +1308,45 @@ export interface CommentResult {
1013
1308
  comment: CommentEntry | null;
1014
1309
  }
1015
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
+
1016
1350
  /** Sheet-wide comment entry returned by `getComments(sheet)`. Extends
1017
1351
  * `CommentEntry` with the anchor cell so comments on otherwise-empty
1018
1352
  * cells can be discovered without already knowing their `(row, col)`. */
@@ -1344,9 +1678,21 @@ export interface ConditionalFormatEntry {
1344
1678
  /** Lower bound of the lowest icon's bucket; a cell below it gets no
1345
1679
  * icon. Always present on a rule read back from a workbook. */
1346
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>;
1347
1684
  };
1348
1685
  }
1349
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
+
1350
1696
  /** Argument shape accepted by `addConditionalFormat(sheet, rule)`.
1351
1697
  *
1352
1698
  * When `priority` is missing, zero, or negative, the engine assigns
@@ -1412,6 +1758,9 @@ export interface ConditionalFormatInput {
1412
1758
  /** Lower bound of the lowest icon's bucket; a cell below it gets no
1413
1759
  * icon. Omit for Excel's default, `percent 0`. */
1414
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>;
1415
1764
  };
1416
1765
  }
1417
1766
 
@@ -1510,6 +1859,16 @@ export interface FontRecord {
1510
1859
  hasItalic: boolean;
1511
1860
  /** Whether the source carried a `<strike>` element at all. */
1512
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;
1513
1872
  /** 0=none, 1=single, 2=double, 3=singleAccounting, 4=doubleAccounting. */
1514
1873
  underline: number;
1515
1874
  /** 0=baseline, 1=superscript, 2=subscript. */
@@ -1547,6 +1906,31 @@ export interface FillRecord {
1547
1906
  fg: ColorSpec;
1548
1907
  /** Original `<bgColor>` specification, preserved for round-tripping. */
1549
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;
1550
1934
  }
1551
1935
 
1552
1936
  /** One side of a `BorderRecord`. */
@@ -1654,6 +2038,17 @@ export interface PhoneticProperties {
1654
2038
  /** Return type of `Workbook.getCellPhoneticProperties(sheet, row, col)`. */
1655
2039
  export interface PhoneticPropertiesResult extends PhoneticProperties {
1656
2040
  status: Status;
2041
+ /** `true` when the triple came from an explicit `<phoneticPr>` element or
2042
+ * `setCellPhoneticProperties` (an all-zero triple included); `false` for
2043
+ * the state an absent element resolves to. Python reads it through
2044
+ * `has_phonetic_properties`. */
2045
+ present: boolean;
2046
+ }
2047
+
2048
+ /** Return type of `Workbook.getCellShowPhonetic(sheet, row, col)`. */
2049
+ export interface CellShowPhoneticResult {
2050
+ status: Status;
2051
+ show: boolean;
1657
2052
  }
1658
2053
 
1659
2054
  /** Return type of `Workbook.getFont(fontIndex)`. */
@@ -1903,6 +2298,48 @@ export enum AnchorEditAs {
1903
2298
  Absolute = 2,
1904
2299
  }
1905
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
+
1906
2343
  /** Plot group type. Mirrors `fm_chart_plot_type_t`. */
1907
2344
  export enum ChartPlotType {
1908
2345
  Bar = 0,
@@ -2309,7 +2746,8 @@ export interface AutoFilterEvalResult {
2309
2746
 
2310
2747
  /** Result of `Workbook.validateValue`. `hasRule` is false when no rule covers
2311
2748
  * the cell, and `valid` is then true. Otherwise `ruleIndex` indexes
2312
- * `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. */
2313
2751
  export interface ValidationOutcomeResult {
2314
2752
  status: Status;
2315
2753
  hasRule: boolean;
@@ -2443,6 +2881,205 @@ export interface ImagePlacement {
2443
2881
  heightEmu?: number;
2444
2882
  }
2445
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
+
2446
3083
  /** One series input: nothing, a range reference, or literal points. */
2447
3084
  export interface ChartDataSource {
2448
3085
  kind: 'none' | 'ref' | 'literal';
@@ -2938,7 +3575,12 @@ export interface HeaderFooterInput {
2938
3575
  * status 7003 (`kBindingCallbackException`) instead. Cells committed by
2939
3576
  * the sweeps that already ran keep their values, and the workbook stays
2940
3577
  * usable — the next recalc behaves as if the aborted one had been
2941
- * 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. */
2942
3584
  export type IterativeProgressCallback = (
2943
3585
  iteration: number,
2944
3586
  maxResidual: number,
@@ -2968,7 +3610,11 @@ export interface Workbook {
2968
3610
  * contains one of `: \ / ? * [ ]`, or collides case-insensitively (Unicode simple case folding) with an
2969
3611
  * existing sheet, and with `kSheetCountLimitExceeded` at the maximum sheet count. */
2970
3612
  addSheet(name: string): Status;
2971
- /** 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. */
2972
3618
  removeSheet(index: number): Status;
2973
3619
  /** Renames the sheet at `index`. */
2974
3620
  renameSheet(index: number, newName: string): Status;
@@ -2978,6 +3624,17 @@ export interface Workbook {
2978
3624
  sheetCount(): NumberResult;
2979
3625
  /** Display name of the sheet at `idx`; `kInvalidArgument` when `idx` is out of range. */
2980
3626
  sheetName(idx: number): StringResult;
3627
+ /** Returns `{ status, index }`: the sheet the first `<workbookView>` marks
3628
+ * active (`activeTab`); without workbook views (an XLSB load) the first
3629
+ * tab-selected sheet; `0` when neither is recorded. Removing or hiding the
3630
+ * active sheet activates the next visible sheet, else the previous one. */
3631
+ activeSheet(): AddStyleResult;
3632
+ /** Marks sheet `sheet` active so a save records it, creating a minimal
3633
+ * `<bookViews>` when the workbook has none. Other `<workbookView>`
3634
+ * attributes survive; `firstSheet` is lowered to `sheet` when larger. The
3635
+ * sheet becomes the only tab-selected one. A sheet index out of range or a
3636
+ * hidden sheet is rejected. */
3637
+ setActiveSheet(sheet: number): Status;
2981
3638
 
2982
3639
  /** Stores a numeric literal. NaN and infinity are rejected with `kInvalidArgument`; so is an out-of-range `sheet`. */
2983
3640
  setNumber(sheet: number, row: number, col: number, value: number): Status;
@@ -3075,6 +3732,13 @@ export interface Workbook {
3075
3732
  /** Returns how the cell's guide renders. A cell with no annotation
3076
3733
  * reports the all-zero triple. */
3077
3734
  getCellPhoneticProperties(sheet: number, row: number, col: number): PhoneticPropertiesResult;
3735
+ /** Reads the cell's "Show Phonetic" flag (`<c ph="1">`); `false` for an
3736
+ * absent cell. */
3737
+ getCellShowPhonetic(sheet: number, row: number, col: number): CellShowPhoneticResult;
3738
+ /** Sets the cell's "Show Phonetic" display flag. It is independent of the
3739
+ * readings and survives value writes; a formula cell's flag is neither
3740
+ * saved nor read from a file. */
3741
+ setCellShowPhonetic(sheet: number, row: number, col: number, show: boolean): Status;
3078
3742
 
3079
3743
  /** Recalculates all dirty cells serially on the caller thread.
3080
3744
  *
@@ -3117,21 +3781,36 @@ export interface Workbook {
3117
3781
  * `Workbook`: installing one on another instance leaves this one's
3118
3782
  * registration alone.
3119
3783
  *
3120
- * A value that is not callable is accepted here and reported when the
3121
- * 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. */
3122
3786
  setIterativeProgress(callback: IterativeProgressCallback | null): Status;
3123
3787
 
3124
3788
  /**
3125
3789
  * Workbook-level calc mode (Excel `<calcPr calcMode>` policy).
3126
3790
  *
3127
- * `value` is one of the `CalcMode` codes. The engine itself does NOT gate
3128
- * evaluation on this value — every `recalc()` call honours all dirty
3129
- * cells. The mode is preserved as round-trip metadata and surfaced
3130
- * 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.
3131
3796
  */
3132
3797
  calcMode(): NumberResult<CalcMode>;
3133
- /** 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`. */
3134
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;
3135
3814
 
3136
3815
  /**
3137
3816
  * The workbook's pinned wall-clock reading as `now`, or `now: null` when
@@ -3189,14 +3868,26 @@ export interface Workbook {
3189
3868
  */
3190
3869
 
3191
3870
  /** Inserts `count` rows at `row` on `sheet` and rewrites cross-workbook
3192
- * 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. */
3193
3875
  insertRows(sheet: number, row: number, count: number): Status;
3194
3876
  /** Deletes `count` rows starting at `row` on `sheet`. References that
3195
- * 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. */
3196
3881
  deleteRows(sheet: number, row: number, count: number): Status;
3197
- /** 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. */
3198
3886
  insertCols(sheet: number, col: number, count: number): Status;
3199
- /** 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. */
3200
3891
  deleteCols(sheet: number, col: number, count: number): Status;
3201
3892
 
3202
3893
  /** Number of written coordinates on `sheet`: cells set by any value, formula or format setter,
@@ -3218,6 +3909,9 @@ export interface Workbook {
3218
3909
  * or a sheet-local scope (0-based sheet index). A non-empty `formula`
3219
3910
  * that does not parse is rejected with `kParserUnexpectedToken`. */
3220
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;
3221
3915
 
3222
3916
  /** Number of worksheet tables in the workbook. */
3223
3917
  tableCount(): NumberResult;
@@ -3232,6 +3926,12 @@ export interface Workbook {
3232
3926
  updateTable(idx: number, input: TableUpdateInput): Status;
3233
3927
  /** Removes the table at `idx`. */
3234
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;
3235
3935
 
3236
3936
  /** Reads the complete worksheet-level `<autoFilter>` XML fragment. */
3237
3937
  getSheetAutoFilterXml(sheet: number): SheetAutoFilterXmlResult;
@@ -3312,6 +4012,48 @@ export interface Workbook {
3312
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`. */
3313
4013
  restoreDrawing(sheet: number, bytes: Uint8Array, opts?: RestoreImageOptions): InsertImageResult;
3314
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
+
3315
4057
  // Charts. A chart is addressed as `(sheet, objectId)`, the id `listDrawingObjects` reports for a `DrawingObjectKind.Chart`.
3316
4058
  /** Reads the typed view of the chart `objectId`. */
3317
4059
  getChart(sheet: number, objectId: number): ChartResult;
@@ -3457,21 +4199,57 @@ export interface Workbook {
3457
4199
  ): Status;
3458
4200
  /** Toggles the row / column grand total bands on the pivot. */
3459
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;
3460
4206
  /** Reads the pivot's compact / tabular / outline report layout. */
3461
4207
  pivotGetLayout(sheet: number, pivotIdx: number): PivotReportLayoutResult;
3462
4208
  /** Sets the pivot's compact / tabular / outline report layout. */
3463
4209
  pivotSetLayout(sheet: number, pivotIdx: number, layout: PivotReportLayout): Status;
4210
+ /** Returns `{ status, index: cacheId }`: the cache the pivot draws from.
4211
+ * The definition read-backs here work for pivots created in-session and
4212
+ * loaded from a package alike. */
4213
+ pivotCacheId(sheet: number, pivotIdx: number): AddStyleResult;
4214
+ /** Reads the pivot's name. */
4215
+ pivotName(sheet: number, pivotIdx: number): StringResult;
4216
+ /** Reads the row / column grand total flags `pivotSetGrandTotals` writes. */
4217
+ pivotGetGrandTotals(sheet: number, pivotIdx: number): PivotGrandTotalsResult;
4218
+ /** Reads the table style `pivotSetStyleInfo` writes. */
4219
+ pivotGetStyleInfo(sheet: number, pivotIdx: number): PivotStyleInfoResult;
4220
+ /** Reads the row-axis field order (the list `pivotSetRowFieldOrder` takes). */
4221
+ pivotRowFieldOrder(sheet: number, pivotIdx: number): PivotFieldOrderResult;
4222
+ /** Reads the column-axis field order. */
4223
+ pivotColFieldOrder(sheet: number, pivotIdx: number): PivotFieldOrderResult;
3464
4224
 
3465
4225
  /** Number of fields configured on the pivot. */
3466
4226
  pivotFieldCount(sheet: number, pivotIdx: number): NumberResult;
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. */
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. */
3469
4235
  pivotFieldAdd(sheet: number, pivotIdx: number, spec: PivotFieldSpec): AddStyleResult;
4236
+ /** Reads the definition of field `fieldIdx`. */
4237
+ pivotFieldAt(sheet: number, pivotIdx: number, fieldIdx: number): PivotFieldResult;
4238
+ /** Number of items in the field's item list (what `pivotFieldAddItem` /
4239
+ * `pivotFieldAddItemAt` append to). */
4240
+ pivotFieldItemCount(sheet: number, pivotIdx: number, fieldIdx: number): NumberResult;
4241
+ /** Reads item `itemIdx` of the field; the index `pivotFieldSetItemVisible`
4242
+ * takes. */
4243
+ pivotFieldItemAt(sheet: number, pivotIdx: number, fieldIdx: number, itemIdx: number): PivotItemResult;
3470
4244
  /** Drops every field from the pivot, emptying the row and column orders. */
3471
4245
  pivotFieldClear(sheet: number, pivotIdx: number): Status;
3472
4246
  /** 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. */
3474
- 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;
3475
4253
  /** Sets the sibling order of pivot field `fieldIdx`. `PivotSortOrder.Manual`
3476
4254
  * keeps items in `pivotFieldAddItem` order and takes no `byField`; for the
3477
4255
  * other orders an empty `byField` sorts by label. */
@@ -3510,13 +4288,14 @@ export interface Workbook {
3510
4288
  /** Configures date-grouping on pivot field `fieldIdx`. Pass `-1` for
3511
4289
  * `startYear` / `endYear` to leave the Year-truncation bound unset
3512
4290
  * (meaningful only for `PivotDateGrouping.Year`). `intervalDays` is
3513
- * the `PivotDateGrouping.Days`-only bucket width in whole days; pass
3514
- * `1` for every other granularity. `startSerial` / `endSerial` are
3515
- * the `Days`-only Start/End window as Excel date serials -- pass
3516
- * `-1` for either to leave it auto (Start = the field's data
3517
- * minimum, End = the data maximum plus one day); ignored otherwise.
3518
- * With `Days`, a zero `intervalDays` or a start after the end is
3519
- * 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`. */
3520
4299
  pivotFieldSetDateGroup(
3521
4300
  sheet: number,
3522
4301
  pivotIdx: number,
@@ -3525,9 +4304,9 @@ export interface Workbook {
3525
4304
  calendar: PivotCalendar,
3526
4305
  startYear: number,
3527
4306
  endYear: number,
3528
- intervalDays: number,
3529
- startSerial: number,
3530
- endSerial: number,
4307
+ intervalDays?: number,
4308
+ startSerial?: number,
4309
+ endSerial?: number,
3531
4310
  ): Status;
3532
4311
  /** Removes the date-grouping config from pivot field `fieldIdx`. */
3533
4312
  pivotFieldClearDateGroup(sheet: number, pivotIdx: number, fieldIdx: number): Status;
@@ -3546,25 +4325,26 @@ export interface Workbook {
3546
4325
 
3547
4326
  /** Number of `<dataField>` entries on the pivot. */
3548
4327
  pivotDataFieldCount(sheet: number, pivotIdx: number): NumberResult;
3549
- /** Appends a new data-field entry. */
4328
+ /** Appends a new data-field entry. An omitted or empty `spec.name` is
4329
+ * derived from the workbook profile; see {@link PivotDataFieldSpec}. */
3550
4330
  pivotDataFieldAdd(sheet: number, pivotIdx: number, spec: PivotDataFieldSpec): AddStyleResult;
4331
+ /** Reads data field `dataFieldIdx`. */
4332
+ pivotDataFieldAt(sheet: number, pivotIdx: number, dataFieldIdx: number): PivotDataFieldResult;
3551
4333
  /** Drops every data-field entry from the pivot. */
3552
4334
  pivotDataFieldClear(sheet: number, pivotIdx: number): Status;
3553
- /** Replaces the data-field entry at `dataFieldIdx` in place. */
4335
+ /** Replaces the data-field entry at `dataFieldIdx` in place. An omitted
4336
+ * or empty `spec.name` is derived as in `pivotDataFieldAdd`. */
3554
4337
  pivotDataFieldSet(sheet: number, pivotIdx: number, dataFieldIdx: number, spec: PivotDataFieldSpec): Status;
3555
4338
 
3556
- /** Number of active (slicer-applied) filters on the pivot. Counts only
3557
- * the entries this session added -- see {@link PivotFilterResult}. */
4339
+ /** Number of filters on the pivot -- see {@link PivotFilterResult}. */
3558
4340
  pivotFilterCount(sheet: number, pivotIdx: number): NumberResult;
3559
- /** Appends an active filter. The entry is session state and is not
3560
- * written by `save`; see {@link PivotFilterResult}. */
4341
+ /** Appends a filter, saved with the pivot; see {@link PivotFilterResult}. */
3561
4342
  pivotFilterAdd(sheet: number, pivotIdx: number, spec: PivotFilterSpec): Status;
3562
- /** Reads the active filter at `filterIdx`. The list is session state:
3563
- * see {@link PivotFilterResult}. */
4343
+ /** Reads the filter at `filterIdx`; see {@link PivotFilterResult}. */
3564
4344
  pivotFilterAt(sheet: number, pivotIdx: number, filterIdx: number): PivotFilterResult;
3565
- /** Drops every active filter from the pivot. */
4345
+ /** Drops every listed filter from the pivot. */
3566
4346
  pivotFilterClear(sheet: number, pivotIdx: number): Status;
3567
- /** Removes the active filter at `filterIdx`. */
4347
+ /** Removes the filter at `filterIdx`. */
3568
4348
  pivotFilterRemoveAt(sheet: number, pivotIdx: number, filterIdx: number): Status;
3569
4349
 
3570
4350
  /** Evaluates every CF block on `sheet` against the inclusive range
@@ -3663,13 +4443,15 @@ export interface Workbook {
3663
4443
  * `setSheetVisibility`. `true` on an already very-hidden sheet leaves
3664
4444
  * it very-hidden rather than demoting it, since "hidden" says nothing
3665
4445
  * that sheet does not already satisfy; `false` shows it from either
3666
- * hidden state. */
4446
+ * hidden state. Hiding the only visible sheet fails with
4447
+ * `kInvalidArgument` and leaves it visible. */
3667
4448
  setSheetTabHidden(sheet: number, hidden: boolean): Status;
3668
4449
  /** Sets the sheet tab's visibility to one of the three states. The only
3669
4450
  * way to newly state `SheetVisibility.VeryHidden`, and the only way to
3670
4451
  * demote a very-hidden sheet to plain hidden; `setSheetTabHidden` can
3671
4452
  * express neither. A value outside `SheetVisibility` fails with
3672
- * `kInvalidArgument` and leaves the sheet unchanged. */
4453
+ * `kInvalidArgument` and leaves the sheet unchanged. So does hiding the only
4454
+ * visible sheet. */
3673
4455
  setSheetVisibility(sheet: number, visibility: SheetVisibility): Status;
3674
4456
  /** Sets the sheet's `showGridLines` flag. */
3675
4457
  setSheetShowGridLines(sheet: number, show: boolean): Status;
@@ -3677,10 +4459,31 @@ export interface Workbook {
3677
4459
  setSheetShowRowColHeaders(sheet: number, show: boolean): Status;
3678
4460
  /** Sets the sheet's `showZeros` flag. */
3679
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;
3680
4466
  /** Sets the sheet's `rightToLeft` flag. */
3681
4467
  setSheetRightToLeft(sheet: number, rightToLeft: boolean): Status;
3682
4468
  /** Sets the sheet's `tabSelected` flag. */
3683
4469
  setSheetTabSelected(sheet: number, selected: boolean): Status;
4470
+ /** Sets the sheet view's scroll origin (`<sheetView topLeftCell>`). */
4471
+ setSheetTopLeft(sheet: number, row: number, col: number): Status;
4472
+ /** Sets the first visible cell of a frozen or split view's lower-right
4473
+ * pane. It must lie past any frozen rows and columns; rejected without
4474
+ * panes. Changing the freeze resets it to the first unfrozen cell. */
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;
4481
+ /** Reads the active pane's selection (active cell and ranges). */
4482
+ getSheetSelection(sheet: number): SheetSelectionResult;
4483
+ /** Replaces the active pane's selection. In a frozen or split view the
4484
+ * selection belongs to the pane the view is active in; other panes' are
4485
+ * kept. */
4486
+ setSheetSelection(sheet: number, selection: SheetSelection): Status;
3684
4487
  /** Sets the sheet's `<sheetView view="...">` mode: `""`,
3685
4488
  * `"pageBreakPreview"`, or `"pageLayout"`. Stored verbatim. */
3686
4489
  setSheetViewMode(sheet: number, mode: string): Status;
@@ -3699,12 +4502,16 @@ export interface Workbook {
3699
4502
 
3700
4503
  /** Returns the column-layout overrides on `sheet` in storage order. */
3701
4504
  getSheetColumns(sheet: number): ColumnsResult;
3702
- /** Sets / replaces the column width override on `[first, last]`. */
4505
+ /** Sets / replaces the column width override on `[first, last]`. `width` is a stored width:
4506
+ * characters with the column padding included, as `<col width>` holds it. */
3703
4507
  setColumnWidth(sheet: number, first: number, last: number, width: number): Status;
3704
4508
  /** Sets / replaces the column hidden flag on `[first, last]`. */
3705
4509
  setColumnHidden(sheet: number, first: number, last: number, hidden: boolean): Status;
3706
- /** 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`. */
3707
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;
3708
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. */
3709
4516
  setColumnStyle(sheet: number, first: number, last: number, xfIndex: number): Status;
3710
4517
  /** Removes the cell-style XF on `[first, last]`, retaining other column attributes. */
@@ -3716,8 +4523,11 @@ export interface Workbook {
3716
4523
  setRowHeight(sheet: number, row: number, height: number): Status;
3717
4524
  /** Sets / replaces the row hidden flag at `row`. */
3718
4525
  setRowHidden(sheet: number, row: number, hidden: boolean): Status;
3719
- /** 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`. */
3720
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;
3721
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. */
3722
4532
  setRowStyle(sheet: number, first: number, last: number, xfIndex: number): Status;
3723
4533
  /** Removes the cell-style XF of the inclusive row span `first..last`, retaining other row attributes. */
@@ -3787,14 +4597,15 @@ export interface Workbook {
3787
4597
  getRowHeightPt(sheet: number, row: number): NumberResult;
3788
4598
  /** The character-unit to point conversion model for the workbook's Normal font. */
3789
4599
  getWidthModel(sheet: number, mode: GeometryMode): WidthModelResult;
3790
- /** Converts a column width in characters to points. */
4600
+ /** Converts a stored column width (padding included) to points, snapped to whole screen pixels. */
3791
4601
  columnCharsToPt(sheet: number, mode: GeometryMode, chars: number): NumberResult;
3792
- /** Inverse of `columnCharsToPt`; a width at or below the padding maps to zero characters. */
4602
+ /** Inverse of `columnCharsToPt`: the stored width Excel writes for a column of `pt`. */
3793
4603
  columnPtToChars(sheet: number, mode: GeometryMode, pt: number): NumberResult;
3794
4604
 
3795
4605
  /** Returns `{ status, xfIndex }` for the cell at `(sheet, row, col)`. */
3796
4606
  getCellXfIndex(sheet: number, row: number, col: number): CellXfIndexResult;
3797
- /** 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`. */
3798
4609
  setCellXfIndex(sheet: number, row: number, col: number, xfIndex: number): Status;
3799
4610
  /**
3800
4611
  * Removes the direct style assignment from the cell at `(sheet, row, col)`
@@ -3806,7 +4617,8 @@ export interface Workbook {
3806
4617
  */
3807
4618
  clearCellXfIndex(sheet: number, row: number, col: number): Status;
3808
4619
  /** Applies `xfIndex` across an inclusive rectangle, materialising blank
3809
- * 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`. */
3810
4622
  setRangeXfIndex(
3811
4623
  sheet: number,
3812
4624
  firstRow: number,
@@ -3815,7 +4627,8 @@ export interface Workbook {
3815
4627
  lastCol: number,
3816
4628
  xfIndex: number,
3817
4629
  ): Status;
3818
- /** 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). */
3819
4632
  getCellXf(xfIndex: number): CellXfResult;
3820
4633
  /** Returns the font record at `fontIndex`, including its ColorSpec selector. */
3821
4634
  getFont(fontIndex: number): FontResult;
@@ -3898,6 +4711,25 @@ export interface Workbook {
3898
4711
  * repointed at the Normal style. */
3899
4712
  removeCellStyle(name: string): Status;
3900
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
+
3901
4733
  /** The 12 theme colours (`clrScheme` order) and the theme typefaces. The
3902
4734
  * default theme is reported when the part is absent or unparseable;
3903
4735
  * `source` tells the cases apart. */
@@ -3953,6 +4785,23 @@ export interface Workbook {
3953
4785
  getComments(sheet: number): ListResult<SheetCommentEntry>;
3954
4786
  /** Sets / replaces the cell comment. Pass an empty `text` to remove. */
3955
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;
3956
4805
 
3957
4806
  /** Appends a hyperlink to `sheet`. For an in-workbook link, pass an empty
3958
4807
  * `target` and its A1 destination as `location`. */
@@ -4177,7 +5026,9 @@ export interface FormulonModule {
4177
5026
  *
4178
5027
  * A sink that throws has its exception dropped and the record lost;
4179
5028
  * the call that emitted it is unaffected. Records come from arbitrary
4180
- * 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. */
4181
5032
  setLogSink(sink: ((record: Uint8Array) => void) | null): Status;
4182
5033
  }
4183
5034