@libraz/formulon 0.11.0 → 0.12.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.
@@ -1,10 +1,11 @@
1
1
  //
2
2
  // Hand-written TypeScript declarations for the Formulon WASM bindings.
3
3
  //
4
- // The single entry point is the default export from `formulon.js`,
5
- // which is the Emscripten module factory produced under
6
- // MODULARIZE=1 / EXPORT_NAME=createFormulon / EXPORT_ES6=1. It returns
7
- // a Promise resolving to the Module surface declared below.
4
+ // The entry point is the default export of `@libraz/formulon` (single-
5
+ // threaded) or `@libraz/formulon/threads` (pthread); both are the
6
+ // Emscripten module factory produced under MODULARIZE=1 /
7
+ // EXPORT_NAME=createFormulon / EXPORT_ES6=1 and share this surface. It
8
+ // returns a Promise resolving to the Module surface declared below.
8
9
  //
9
10
  // Mirror of `EMSCRIPTEN_BINDINGS(formulon)` in `src/wasm/embind.cpp`.
10
11
  // Keep this file in sync when adding or removing bindings.
@@ -165,10 +166,20 @@ export enum WorkbookFormat {
165
166
  Xlsb = 2,
166
167
  }
167
168
 
168
- /** Return type of `Workbook.sheetName(idx)`. */
169
- export interface StringResult {
169
+ /** `{ status, value }` returned by the text accessors (`sheetName`,
170
+ * `localizeFunctionName`, `excelProfileId`, ...). `value` is `""` on
171
+ * failure. */
172
+ export interface StringResult<T extends string = string> {
170
173
  status: Status;
171
- value: string;
174
+ value: T;
175
+ }
176
+
177
+ /** `{ status, value }` returned by the numeric accessors (every `*Count`,
178
+ * `calcMode`, ...). `value` is `0` on failure, so a zero count is only
179
+ * meaningful when `status.ok` is true. */
180
+ export interface NumberResult<T extends number = number> {
181
+ status: Status;
182
+ value: T;
172
183
  }
173
184
 
174
185
  /** Return type of `Workbook.cellAt(sheet, idx)`. */
@@ -255,7 +266,7 @@ export interface PivotCell {
255
266
  depth: number;
256
267
  /** Source field name when known. */
257
268
  fieldName: string;
258
- /** Excel number-format code when known. */
269
+ /** The data field's `numFmtId` as a decimal string; empty when unset. */
259
270
  numberFormat: string;
260
271
  }
261
272
 
@@ -334,13 +345,16 @@ export enum PivotFilterType {
334
345
  LabelDate = 5,
335
346
  }
336
347
 
337
- /** Date-grouping granularity. Mirrors `fm_pivot_date_grouping_t`. */
348
+ /** Date-grouping granularity. Mirrors `fm_pivot_date_grouping_t`.
349
+ * `Days` is Excel's "By: Days" grouping (an explicit interval, e.g. a
350
+ * real Excel "week" is `Days` with `intervalDays: 7`); there is no
351
+ * separate week granularity. */
338
352
  export enum PivotDateGrouping {
339
353
  Day = 0,
340
354
  Month = 1,
341
355
  Quarter = 2,
342
356
  Year = 3,
343
- Week = 4,
357
+ Days = 4,
344
358
  Hour = 5,
345
359
  Minute = 6,
346
360
  Second = 7,
@@ -398,6 +412,7 @@ export interface PivotFieldSpec {
398
412
  customName?: string;
399
413
  axis: PivotAxis;
400
414
  subtotalTop?: boolean;
415
+ /** `numFmtId` as a decimal string (built-in or from `addNumFmt`). */
401
416
  numberFormat?: string;
402
417
  }
403
418
 
@@ -408,6 +423,7 @@ export interface PivotDataFieldSpec {
408
423
  name: string;
409
424
  fieldIndex: number;
410
425
  aggregation: PivotAggregation;
426
+ /** `numFmtId` as a decimal string (built-in or from `addNumFmt`). */
411
427
  numberFormat?: string;
412
428
  showAs?: PivotShowValuesAs;
413
429
  showAsBaseField?: number;
@@ -519,6 +535,13 @@ export interface CivilTime {
519
535
  second: number;
520
536
  }
521
537
 
538
+ /** Return type of `Workbook.pinnedNow()`. `now` is `null` when the workbook
539
+ * follows the host clock, and on failure. */
540
+ export interface PinnedNowResult {
541
+ status: Status;
542
+ now: CivilTime | null;
543
+ }
544
+
522
545
  /** RGBA colour. Channels are 0-255 (sRGB). */
523
546
  export interface CfColor {
524
547
  r: number;
@@ -554,6 +577,9 @@ export interface CfMatch {
554
577
  barBorderEngaged: number;
555
578
  barBorder: CfColor;
556
579
  barGradient: number;
580
+ /** The rule's direction (0 = context, 1 = left to right, 2 = right to
581
+ * left); the bar geometry is stated from the left edge. */
582
+ barDirection: number;
557
583
  /** Active when `kind === IconSet`; ordinal of `formulon::cf::IconSetName`. */
558
584
  iconSetName: number;
559
585
  iconIndex: number;
@@ -919,8 +945,10 @@ export function mergeFunctionMetadata(
919
945
  /** Signature of {@link mergeFunctionMetadata}. */
920
946
  export type MergeFunctionMetadata = typeof mergeFunctionMetadata;
921
947
 
922
- /** Spill region info returned by `spillInfo(sheet, row, col)`. */
948
+ /** Spill region info returned by `spillInfo(sheet, row, col)`. On failure
949
+ * `engaged` is `false` and the other fields are zero. */
923
950
  export interface SpillInfo {
951
+ readonly status: Status;
924
952
  readonly engaged: boolean;
925
953
  readonly anchorRow: number;
926
954
  readonly anchorCol: number;
@@ -1002,6 +1030,9 @@ export interface ConditionalFormatEntry {
1002
1030
  readonly border?: CfColor;
1003
1031
  readonly negativeBorder?: CfColor;
1004
1032
  readonly axisColor?: CfColor;
1033
+ /** Edge the bar grows from: 0 = context (the sheet's reading
1034
+ * direction), 1 = left to right, 2 = right to left. */
1035
+ readonly direction: number;
1005
1036
  };
1006
1037
  /** Engaged for `iconSet` rules. */
1007
1038
  readonly iconSet?: {
@@ -1013,6 +1044,9 @@ export interface ConditionalFormatEntry {
1013
1044
  * and save but never consulted during evaluation. Each threshold
1014
1045
  * carries its own `type`, and that type is what interprets it. */
1015
1046
  readonly percent: boolean;
1047
+ /** Lower bound of the lowest icon's bucket; a cell below it gets no
1048
+ * icon. Always present on a rule read back from a workbook. */
1049
+ readonly floor?: CfValueObjectInput;
1016
1050
  };
1017
1051
  }
1018
1052
 
@@ -1064,6 +1098,8 @@ export interface ConditionalFormatInput {
1064
1098
  border?: CfColor;
1065
1099
  negativeBorder?: CfColor;
1066
1100
  axisColor?: CfColor;
1101
+ /** 0 = context (default), 1 = left to right, 2 = right to left. */
1102
+ direction?: number;
1067
1103
  };
1068
1104
  /** Payload for type 4 (`iconSet`). `name` is `formulon::cf::IconSetName` ordinal. */
1069
1105
  iconSet?: {
@@ -1075,6 +1111,9 @@ export interface ConditionalFormatInput {
1075
1111
  * consulted during evaluation (each threshold's own `type` is
1076
1112
  * authoritative). */
1077
1113
  percent?: boolean;
1114
+ /** Lower bound of the lowest icon's bucket; a cell below it gets no
1115
+ * icon. Omit for Excel's default, `percent 0`. */
1116
+ floor?: CfValueObjectInput;
1078
1117
  };
1079
1118
  }
1080
1119
 
@@ -1170,6 +1209,9 @@ export interface FontRecord {
1170
1209
  hasCharset: boolean;
1171
1210
  /** OOXML charset codepage id (e.g. 128 = Shift_JIS). */
1172
1211
  charset: number;
1212
+ /** `<scheme>` theme link: 0=absent, 1=major, 2=minor. Meaningful only on
1213
+ * a workbook that carries a theme part. */
1214
+ scheme: number;
1173
1215
  /** AARRGGBB literal RGB or compatibility fallback; not a resolved
1174
1216
  * theme/indexed/auto render colour. */
1175
1217
  colorArgb: number;
@@ -1252,6 +1294,37 @@ export interface CellXf {
1252
1294
  xfId?: number;
1253
1295
  }
1254
1296
 
1297
+ /** One `<rPh>` block: `text` reads the half-open span `[sb, eb)` of the
1298
+ * cell's surface text, measured in UTF-16 code units. */
1299
+ export interface PhoneticRun {
1300
+ sb: number;
1301
+ eb: number;
1302
+ text: string;
1303
+ }
1304
+
1305
+ /** Return type of `Workbook.getCellPhoneticRuns(sheet, row, col)`. */
1306
+ export interface PhoneticRunsResult {
1307
+ status: Status;
1308
+ runs: PhoneticRun[];
1309
+ }
1310
+
1311
+ /** How a cell's phonetic guide renders (OOXML `<phoneticPr>`). `fontId`
1312
+ * indexes the workbook's font table for the ruby text; `type` is the kana
1313
+ * form (0 half-width katakana, 1 full-width katakana, 2 hiragana, 3 no
1314
+ * conversion) and `alignment` how the kana is distributed (0 no control,
1315
+ * 1 left, 2 center, 3 distributed). The all-zero triple is what Excel
1316
+ * infers for a guide written with no `<phoneticPr>` element. */
1317
+ export interface PhoneticProperties {
1318
+ fontId: number;
1319
+ type: number;
1320
+ alignment: number;
1321
+ }
1322
+
1323
+ /** Return type of `Workbook.getCellPhoneticProperties(sheet, row, col)`. */
1324
+ export interface PhoneticPropertiesResult extends PhoneticProperties {
1325
+ status: Status;
1326
+ }
1327
+
1255
1328
  /** Return type of `Workbook.getFont(fontIndex)`. */
1256
1329
  export interface FontResult extends FontRecord {
1257
1330
  status: Status;
@@ -1583,7 +1656,10 @@ export type IterativeProgressCallback = (
1583
1656
  export interface Workbook {
1584
1657
  /** True when the wrapper holds a live native handle. */
1585
1658
  isValid(): boolean;
1586
- /** Releases the native handle. The instance must not be used afterwards. */
1659
+ /** Releases the native handle. The instance must not be used afterwards.
1660
+ * Throws, and leaves the handle intact, if called from inside this
1661
+ * workbook's own iterative-progress callback -- that callback is still
1662
+ * running a `recalc`/`recalcParallel` against the handle. */
1587
1663
  delete(): void;
1588
1664
 
1589
1665
  save(): SaveResult;
@@ -1600,16 +1676,30 @@ export interface Workbook {
1600
1676
  renameSheet(index: number, newName: string): Status;
1601
1677
  /** Moves the sheet from `fromIdx` to `toIdx` (post-removal index). */
1602
1678
  moveSheet(fromIdx: number, toIdx: number): Status;
1603
- sheetCount(): number;
1679
+ sheetCount(): NumberResult;
1604
1680
  sheetName(idx: number): StringResult;
1605
1681
 
1606
1682
  setNumber(sheet: number, row: number, col: number, value: number): Status;
1607
1683
  setBool(sheet: number, row: number, col: number, value: boolean): Status;
1608
- /** Stores a static Excel error literal; `errorCode` is an ErrorCode ordinal. */
1684
+ /** Stores a static Excel error literal; `errorCode` is an ErrorCode
1685
+ * ordinal. Unlike `setNumber`/`setBool`/`setText`, an omitted
1686
+ * `errorCode` has no sane zero-value default, so it is rejected
1687
+ * rather than silently writing error code 0 (`#NULL!`). */
1609
1688
  setError(sheet: number, row: number, col: number, errorCode: number): Status;
1610
1689
  setText(sheet: number, row: number, col: number, text: string): Status;
1611
1690
  /** Stores (or, when empty, clears) the cell's OOXML phonetic guide (`<rPh>`). */
1612
1691
  setCellPhonetic(sheet: number, row: number, col: number, phonetic: string): Status;
1692
+ /** Stores (or, when empty, clears) the cell's phonetic guide as one `<rPh>`
1693
+ * block per run. Unlike `setCellPhonetic`, which annotates the whole cell,
1694
+ * this keeps the span each reading covers. The runs must be an ordered
1695
+ * partition: each needs `sb <= eb` and must start at or after the previous
1696
+ * run's `eb`. */
1697
+ setCellPhoneticRuns(sheet: number, row: number, col: number, runs: PhoneticRun[]): Status;
1698
+ /** Stores how the cell's guide renders. Independent of
1699
+ * `setCellPhoneticRuns` in both directions, and only observable on a cell
1700
+ * that has runs; every value setter clears both, so call it after the
1701
+ * cell's text. */
1702
+ setCellPhoneticProperties(sheet: number, row: number, col: number, properties: PhoneticProperties): Status;
1613
1703
  setBlank(sheet: number, row: number, col: number): Status;
1614
1704
  setFormula(sheet: number, row: number, col: number, formula: string): Status;
1615
1705
 
@@ -1619,8 +1709,8 @@ export interface Workbook {
1619
1709
  * single scalar result, without mutating the workbook. Local and
1620
1710
  * cross-sheet references, defined names, and `ROW()` / `COLUMN()` resolve
1621
1711
  * relative to the anchor. An array / spill result is reduced to its
1622
- * top-left element (a pragmatic API shape, not Excel implicit
1623
- * intersection or spilling; multi-cell results are a Phase 2 follow-up).
1712
+ * top-left element (not Excel implicit intersection or spilling; use
1713
+ * `evaluateFormulaArray` for the whole multi-cell result).
1624
1714
  * Note: a self-reference reads the target cell's cached value rather than
1625
1715
  * raising `#REF!`, since the ad-hoc formula never joins the dep graph. */
1626
1716
  evaluateFormulaText(sheet: number, row: number, col: number, formula: string): EvalResult;
@@ -1654,6 +1744,12 @@ export interface Workbook {
1654
1744
  getLambdaText(sheet: number, row: number, col: number): LambdaTextResult;
1655
1745
  /** Returns the cell's OOXML phonetic guide (`<rPh>`), or an empty string. */
1656
1746
  getCellPhonetic(sheet: number, row: number, col: number): StringResult;
1747
+ /** Returns the cell's `<rPh>` blocks with their spans. `getCellPhonetic`
1748
+ * returns the same readings concatenated, without the spans. */
1749
+ getCellPhoneticRuns(sheet: number, row: number, col: number): PhoneticRunsResult;
1750
+ /** Returns how the cell's guide renders. A cell with no annotation
1751
+ * reports the all-zero triple. */
1752
+ getCellPhoneticProperties(sheet: number, row: number, col: number): PhoneticPropertiesResult;
1657
1753
 
1658
1754
  /** Recalculates all dirty cells serially on the caller thread.
1659
1755
  *
@@ -1672,6 +1768,9 @@ export interface Workbook {
1672
1768
  * through `Number.MAX_SAFE_INTEGER` (2^53 - 1).
1673
1769
  * As with `recalc`, a throwing `IterativeProgressCallback` is reported as
1674
1770
  * status 7003 with the counters left at zero.
1771
+ * Only `@libraz/formulon/threads` starts workers. The default
1772
+ * `@libraz/formulon` build has no pthreads, so the same pass runs
1773
+ * serially with `workerThreadsStarted` at 0.
1675
1774
  */
1676
1775
  recalcParallel(threadCount: number): ParallelRecalcResult;
1677
1776
  /** Recalculates only cells touched by the supplied viewport. Reports
@@ -1697,17 +1796,17 @@ export interface Workbook {
1697
1796
  /**
1698
1797
  * Workbook-level calc mode (Excel `<calcPr calcMode>` policy).
1699
1798
  *
1700
- * Returns one of `CalcMode` codes. The engine itself does NOT gate
1799
+ * `value` is one of the `CalcMode` codes. The engine itself does NOT gate
1701
1800
  * evaluation on this value — every `recalc()` call honours all dirty
1702
1801
  * cells. The mode is preserved as round-trip metadata and surfaced
1703
1802
  * here so the UI can mirror Excel's user-visible state.
1704
1803
  */
1705
- calcMode(): CalcMode;
1804
+ calcMode(): NumberResult<CalcMode>;
1706
1805
  setCalcMode(mode: CalcMode): Status;
1707
1806
 
1708
1807
  /**
1709
- * The workbook's pinned wall-clock reading, or `null` when it follows the
1710
- * host clock (the default).
1808
+ * The workbook's pinned wall-clock reading as `now`, or `now: null` when
1809
+ * it follows the host clock (the default).
1711
1810
  *
1712
1811
  * Pinning gives `NOW()`, `TODAY()` and the pivot relative-period filters
1713
1812
  * ("this month", "year to date", ...) one instant to agree on. Without a
@@ -1729,36 +1828,29 @@ export interface Workbook {
1729
1828
  * pin is a calendar instant, not a normalising constructor: a month of 13
1730
1829
  * is rejected rather than rolled into the next year.
1731
1830
  */
1732
- pinnedNow(): CivilTime | null;
1831
+ pinnedNow(): PinnedNowResult;
1733
1832
  setPinnedNow(year: number, month: number, day: number, hour: number, minute: number, second: number): Status;
1734
1833
  clearPinnedNow(): Status;
1735
1834
 
1736
1835
  /**
1737
1836
  * Full formula-behaviour profile id. Defaults to `win-365-ja_JP`.
1738
1837
  */
1739
- excelProfileId(): ExcelProfileId;
1838
+ excelProfileId(): StringResult<ExcelProfileId>;
1740
1839
  setExcelProfileId(profileId: ExcelProfileId): Status;
1741
1840
 
1742
1841
  /**
1743
1842
  * The four structural edits move every structure the engine models:
1744
1843
  * cells, formulas, merges, conditional-format ranges, validations,
1745
1844
  * hyperlinks, tables, print areas, manual breaks and the auto-filter
1746
- * range.
1747
- *
1748
- * They do not move coordinates held in worksheet content the engine
1749
- * keeps byte-verbatim because it does not model it — the worksheet
1750
- * `<extLst>` (the `x14` conditional-formatting block behind DataBar
1751
- * negative-fill / axis / gradient settings, sparkline groups, slicer
1752
- * anchors) and any unmodelled `<worksheet>` child kept so a save does
1753
- * not drop it. Those keep their pre-edit rectangles.
1845
+ * range. The ranges and formulas inside the worksheet `<extLst>` (the
1846
+ * `x14` conditional-formatting block, sparkline groups, `x14`
1847
+ * validations) move with them, as Excel moves them.
1754
1848
  *
1755
- * What that looks like in Excel differs per extension: it drops an
1756
- * `x14` entry whose range no longer matches the legacy rule it extends,
1757
- * so an extended DataBar quietly reverts to its legacy rendering, while
1758
- * a sparkline group keeps drawing and reads its source range from the
1759
- * wrong cells. Neither raises a status or a diagnostic counter. Re-author
1760
- * those extensions after editing rows or columns on a sheet that carries
1761
- * them.
1849
+ * They do not move an unmodelled `<worksheet>` child kept byte-verbatim
1850
+ * so a save does not drop it (a `<sortState>`, for one): a `ref` inside
1851
+ * it keeps its pre-edit rectangle, and nothing reports it. An insert also
1852
+ * does not copy the formatting of the row or column before it onto the
1853
+ * new one, which Excel does — a sparkline included.
1762
1854
  */
1763
1855
 
1764
1856
  /** Inserts `count` rows at `row` on `sheet` and rewrites cross-workbook
@@ -1772,10 +1864,10 @@ export interface Workbook {
1772
1864
  /** Deletes `count` columns starting at `col` on `sheet`. */
1773
1865
  deleteCols(sheet: number, col: number, count: number): Status;
1774
1866
 
1775
- cellCount(sheet: number): number;
1867
+ cellCount(sheet: number): NumberResult;
1776
1868
  cellAt(sheet: number, idx: number): CellEntry;
1777
1869
 
1778
- definedNameCount(): number;
1870
+ definedNameCount(): NumberResult;
1779
1871
  definedNameAt(idx: number): DefinedNameEntry;
1780
1872
  /** Adds, replaces, or (when `formula` is empty) removes a workbook-
1781
1873
  * scoped defined name. */
@@ -1784,7 +1876,7 @@ export interface Workbook {
1784
1876
  * or a sheet-local scope (0-based sheet index). */
1785
1877
  setDefinedNameScoped(name: string, formula: string, localSheetId: number): Status;
1786
1878
 
1787
- tableCount(): number;
1879
+ tableCount(): NumberResult;
1788
1880
  tableAt(idx: number): TableEntry;
1789
1881
  createTable(input: TableInput): AddStyleResult;
1790
1882
  /** Partially updates a table. Omitted fields preserve their current
@@ -1798,17 +1890,17 @@ export interface Workbook {
1798
1890
  /** Replaces the worksheet-level `<autoFilter>` XML fragment; empty clears it. */
1799
1891
  setSheetAutoFilterXml(sheet: number, xml: string): Status;
1800
1892
 
1801
- passthroughCount(): number;
1893
+ passthroughCount(): NumberResult;
1802
1894
  passthroughAt(idx: number): PassthroughEntry;
1803
1895
 
1804
1896
  /** Returns the number of PivotTables anchored on `sheet`. */
1805
- pivotCount(sheet: number): number;
1897
+ pivotCount(sheet: number): NumberResult;
1806
1898
  /** Evaluates and projects a PivotTable into concrete grid cells. */
1807
1899
  pivotLayout(sheet: number, pivotIndex: number): PivotLayoutResult;
1808
1900
 
1809
1901
  // ---- PivotCache mutation -----------------------------------------------
1810
1902
  /** Returns the number of pivot caches owned by the workbook. */
1811
- pivotCacheCount(): number;
1903
+ pivotCacheCount(): NumberResult;
1812
1904
  /** Returns `{ status, index: cacheId }` for the cache at flat
1813
1905
  * index `idx`. */
1814
1906
  pivotCacheIdAt(idx: number): AddStyleResult;
@@ -1824,7 +1916,7 @@ export interface Workbook {
1824
1916
  pivotCacheSetWorksheetSource(cacheId: number, source: PivotWorksheetSource): Status;
1825
1917
 
1826
1918
  /** Number of fields on the cache identified by `cacheId`. */
1827
- pivotCacheFieldCount(cacheId: number): number;
1919
+ pivotCacheFieldCount(cacheId: number): NumberResult;
1828
1920
  /** Reads the name of the cache field at `fieldIdx`. */
1829
1921
  pivotCacheFieldName(cacheId: number, fieldIdx: number): StringResult;
1830
1922
  /** Appends a new field with the given UTF-8 name to the cache.
@@ -1834,7 +1926,7 @@ export interface Workbook {
1834
1926
  pivotCacheFieldClear(cacheId: number): Status;
1835
1927
 
1836
1928
  /** Number of shared items configured on cache field `fieldIdx`. */
1837
- pivotCacheFieldSharedItemCount(cacheId: number, fieldIdx: number): number;
1929
+ pivotCacheFieldSharedItemCount(cacheId: number, fieldIdx: number): NumberResult;
1838
1930
  /** Appends a numeric shared item to cache field `fieldIdx`. */
1839
1931
  pivotCacheFieldAddSharedItemNumber(cacheId: number, fieldIdx: number, value: number): Status;
1840
1932
  /** Appends a text shared item to cache field `fieldIdx`. */
@@ -1849,7 +1941,7 @@ export interface Workbook {
1849
1941
  pivotCacheFieldClearSharedItems(cacheId: number, fieldIdx: number): Status;
1850
1942
 
1851
1943
  /** Returns the number of records on the cache. */
1852
- pivotCacheRecordCount(cacheId: number): number;
1944
+ pivotCacheRecordCount(cacheId: number): NumberResult;
1853
1945
  /** Appends a new empty record. `index` carries the new record's index. */
1854
1946
  pivotCacheRecordAdd(cacheId: number): AddStyleResult;
1855
1947
  /** Drops every record from the cache. */
@@ -1889,7 +1981,7 @@ export interface Workbook {
1889
1981
  pivotSetLayout(sheet: number, pivotIdx: number, layout: PivotReportLayout): Status;
1890
1982
 
1891
1983
  /** Number of fields configured on the pivot. */
1892
- pivotFieldCount(sheet: number, pivotIdx: number): number;
1984
+ pivotFieldCount(sheet: number, pivotIdx: number): NumberResult;
1893
1985
  /** Appends a new field. Returns `{ status, index: fieldIdx }`. */
1894
1986
  pivotFieldAdd(sheet: number, pivotIdx: number, spec: PivotFieldSpec): AddStyleResult;
1895
1987
  /** Drops every field from the pivot. */
@@ -1901,10 +1993,6 @@ export interface Workbook {
1901
1993
  pivotFieldSetSort(sheet: number, pivotIdx: number, fieldIdx: number, ascending: boolean, byField: string): Status;
1902
1994
  /** Sets the `subtotal_top` flag on pivot field `fieldIdx`. */
1903
1995
  pivotFieldSetSubtotalTop(sheet: number, pivotIdx: number, fieldIdx: number, top: boolean): Status;
1904
- /** Appends an aggregation to pivot field `fieldIdx`. */
1905
- pivotFieldAddAggregation(sheet: number, pivotIdx: number, fieldIdx: number, agg: PivotAggregation): Status;
1906
- /** Drops every aggregation from pivot field `fieldIdx`. */
1907
- pivotFieldClearAggregations(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1908
1996
  /** Appends a manual-filter item to pivot field `fieldIdx`, addressed by
1909
1997
  * its label. The item carries no cache binding, so the filter engine
1910
1998
  * matches source records by comparing their rendered label against
@@ -1934,7 +2022,15 @@ export interface Workbook {
1934
2022
  /** Drops every subtotal-fn entry from pivot field `fieldIdx`. */
1935
2023
  pivotFieldClearSubtotalFns(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1936
2024
  /** Configures date-grouping on pivot field `fieldIdx`. Pass `-1` for
1937
- * `startYear` / `endYear` to leave the bound unset. */
2025
+ * `startYear` / `endYear` to leave the Year-truncation bound unset
2026
+ * (meaningful only for `PivotDateGrouping.Year`). `intervalDays` is
2027
+ * the `PivotDateGrouping.Days`-only bucket width in whole days; pass
2028
+ * `1` for every other granularity. `startSerial` / `endSerial` are
2029
+ * the `Days`-only Start/End window as Excel date serials -- pass
2030
+ * `-1` for either to leave it auto (Start = the field's data
2031
+ * minimum, End = the data maximum plus one day); ignored otherwise.
2032
+ * With `Days`, a zero `intervalDays` or a start after the end is
2033
+ * rejected with `kInvalidArgument`. */
1938
2034
  pivotFieldSetDateGroup(
1939
2035
  sheet: number,
1940
2036
  pivotIdx: number,
@@ -1943,11 +2039,15 @@ export interface Workbook {
1943
2039
  calendar: PivotCalendar,
1944
2040
  startYear: number,
1945
2041
  endYear: number,
2042
+ intervalDays: number,
2043
+ startSerial: number,
2044
+ endSerial: number,
1946
2045
  ): Status;
1947
2046
  /** Removes the date-grouping config from pivot field `fieldIdx`. */
1948
2047
  pivotFieldClearDateGroup(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1949
- /** Sets the OOXML number-format string on pivot field `fieldIdx`.
1950
- * Pass an empty string to clear. */
2048
+ /** Sets the `numFmtId` of pivot field `fieldIdx`, as a decimal string
2049
+ * naming a built-in id or one returned by `addNumFmt`. Pass an empty
2050
+ * string to clear; any other unknown id is rejected. */
1951
2051
  pivotFieldSetNumberFormat(sheet: number, pivotIdx: number, fieldIdx: number, utf8: string): Status;
1952
2052
 
1953
2053
  /** Replaces the row-axis field order with `indices`. Each entry must
@@ -1957,7 +2057,7 @@ export interface Workbook {
1957
2057
  pivotSetColFieldOrder(sheet: number, pivotIdx: number, indices: ReadonlyArray<number>): Status;
1958
2058
 
1959
2059
  /** Number of `<dataField>` entries on the pivot. */
1960
- pivotDataFieldCount(sheet: number, pivotIdx: number): number;
2060
+ pivotDataFieldCount(sheet: number, pivotIdx: number): NumberResult;
1961
2061
  /** Appends a new data-field entry. */
1962
2062
  pivotDataFieldAdd(sheet: number, pivotIdx: number, spec: PivotDataFieldSpec): AddStyleResult;
1963
2063
  /** Drops every data-field entry from the pivot. */
@@ -1967,7 +2067,7 @@ export interface Workbook {
1967
2067
 
1968
2068
  /** Number of active (slicer-applied) filters on the pivot. Counts only
1969
2069
  * the entries this session added -- see {@link PivotFilterResult}. */
1970
- pivotFilterCount(sheet: number, pivotIdx: number): number;
2070
+ pivotFilterCount(sheet: number, pivotIdx: number): NumberResult;
1971
2071
  /** Appends an active filter. The entry is session state and is not
1972
2072
  * written by `save`; see {@link PivotFilterResult}. */
1973
2073
  pivotFilterAdd(sheet: number, pivotIdx: number, spec: PivotFilterSpec): Status;
@@ -2157,6 +2257,16 @@ export interface Workbook {
2157
2257
  /** Adds a font (deduplicating against existing entries) and returns
2158
2258
  * the resolved index. */
2159
2259
  addFont(record: FontRecord): AddStyleResult;
2260
+ /** Overwrites the font at `fontIndex` in place. Every `<xf>` naming that
2261
+ * index restyles at once, so this is a bulk change rather than a local
2262
+ * edit; `addFont` is the way to introduce a new appearance. The index
2263
+ * must already exist -- the table does not auto-grow. */
2264
+ setFont(fontIndex: number, record: FontRecord): Status;
2265
+ /** Declares the workbook's default font: font 0, the record an unstyled
2266
+ * cell resolves to. A new workbook seeds it with Excel's Calibri 11 and
2267
+ * `addFont` can only append beside it, so this is the way to change what
2268
+ * a never-styled cell is saved as. Read it back with `getFont(0)`. */
2269
+ setDefaultFont(record: FontRecord): Status;
2160
2270
  /** Adds a fill (deduplicating against existing entries). */
2161
2271
  addFill(record: FillRecord): AddStyleResult;
2162
2272
  /** Adds a border (deduplicating against existing entries). */
@@ -2178,24 +2288,24 @@ export interface Workbook {
2178
2288
  addDxf(record: DxfRecord): AddStyleResult;
2179
2289
 
2180
2290
  /** Returns the number of font records currently registered. */
2181
- fontCount(): number;
2291
+ fontCount(): NumberResult;
2182
2292
  /** Returns the number of fill records currently registered. */
2183
- fillCount(): number;
2293
+ fillCount(): NumberResult;
2184
2294
  /** Returns the number of border records currently registered. */
2185
- borderCount(): number;
2295
+ borderCount(): NumberResult;
2186
2296
  /** Returns the number of `<xf>` records currently registered. */
2187
- xfCount(): number;
2297
+ xfCount(): NumberResult;
2188
2298
  /** Returns the number of `<dxf>` records available for CF `dxfId`. */
2189
- dxfCount(): number;
2299
+ dxfCount(): NumberResult;
2190
2300
 
2191
2301
  /** Returns the number of named cell styles (`<cellStyle>` entries)
2192
2302
  * registered. Zero for workbooks that do not declare any named
2193
2303
  * styles. */
2194
- cellStyleCount(): number;
2304
+ cellStyleCount(): NumberResult;
2195
2305
  /** Returns the number of `<cellStyleXfs>` records — the named-style
2196
2306
  * xf table referenced by `CellStyleResult.xfId`. Independent of the
2197
2307
  * per-cell `cellXfs` table. */
2198
- cellStyleXfCount(): number;
2308
+ cellStyleXfCount(): NumberResult;
2199
2309
  /** Returns the named cell style at `index`. Out-of-range indices
2200
2310
  * surface `kInvalidArgument` via `status`. */
2201
2311
  getCellStyle(index: number): CellStyleResult;
@@ -2304,11 +2414,12 @@ export interface Workbook {
2304
2414
  /** Returns the cells that `(sheet, row, col)` directly reads
2305
2415
  * (1-step precedents) when `depth <= 1`, or every cell reached
2306
2416
  * within `depth` BFS steps otherwise. `depth` is capped at 32 to
2307
- * avoid runaway expansion in cyclic graphs. */
2308
- precedents(sheet: number, row: number, col: number, depth: number): ReadonlyArray<CellNode>;
2417
+ * avoid runaway expansion in cyclic graphs. An invalid sheet, row or
2418
+ * column yields an empty list with `status.ok === false`. */
2419
+ precedents(sheet: number, row: number, col: number, depth: number): ListResult<CellNode>;
2309
2420
  /** Returns the cells that read `(sheet, row, col)` directly
2310
2421
  * (1-step dependents). Same depth semantics as `precedents`. */
2311
- dependents(sheet: number, row: number, col: number, depth: number): ReadonlyArray<CellNode>;
2422
+ dependents(sheet: number, row: number, col: number, depth: number): ListResult<CellNode>;
2312
2423
 
2313
2424
  /** Returns metadata for the function `name` (case-insensitive). When
2314
2425
  * the function is unknown, returns `{ok: false}`. `locale` selects
@@ -2318,20 +2429,21 @@ export interface Workbook {
2318
2429
  functionMetadata(name: string, locale: number): FunctionMetadataResult;
2319
2430
  /** Returns every registered function's canonical name in ascending
2320
2431
  * sort order. */
2321
- functionNames(): ReadonlyArray<string>;
2432
+ functionNames(): ListResult<string>;
2322
2433
 
2323
2434
  /** Returns the localized display name for the canonical function
2324
2435
  * `canonicalName` in `locale`. No alias table exists in any locale,
2325
2436
  * so this always returns the canonical name unchanged; localized
2326
- * display names belong to the host's provider document. Returns the
2327
- * empty string when the canonical name does not match a registered
2328
- * function. */
2329
- localizeFunctionName(canonicalName: string, locale: number): string;
2437
+ * display names belong to the host's provider document. `value` is
2438
+ * the empty string, with `status.ok === false`, when the canonical
2439
+ * name does not match a registered function. */
2440
+ localizeFunctionName(canonicalName: string, locale: number): StringResult;
2330
2441
  /** Inverse of `localizeFunctionName`: returns the canonical English
2331
2442
  * name for the localized function `localizedName`. With no alias
2332
2443
  * table this is a case-insensitive canonical-name match, in every
2333
- * locale. Returns the empty string when no function matches. */
2334
- canonicalizeFunctionName(localizedName: string, locale: number): string;
2444
+ * locale. `value` is the empty string, with `status.ok === false`,
2445
+ * when no function matches. */
2446
+ canonicalizeFunctionName(localizedName: string, locale: number): StringResult;
2335
2447
 
2336
2448
  /** Returns dynamic-array spill info for `(sheet, row, col)`.
2337
2449
  * When the cell is part of a spill region (anchor or phantom),
@@ -2348,9 +2460,10 @@ export interface WorkbookCtor {
2348
2460
  createDefault(): Workbook;
2349
2461
  /** Workbook with no sheets. */
2350
2462
  createEmpty(): Workbook;
2351
- /** Loads from an in-memory `.xlsx` byte buffer. The returned wrapper
2352
- * may be invalid (`!isValid()`) on failure; consult
2353
- * `lastErrorMessage()` for diagnostics. */
2463
+ /** Loads from an in-memory workbook byte buffer, auto-detecting
2464
+ * `.xlsx` vs `.xlsb` from the package contents (there is no filename
2465
+ * to route on). The returned wrapper may be invalid (`!isValid()`) on
2466
+ * failure; consult `lastErrorMessage()` for diagnostics. */
2354
2467
  loadBytes(bytes: Uint8Array): Workbook;
2355
2468
  }
2356
2469