@libraz/formulon 0.11.1 → 0.13.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.
@@ -21,7 +22,8 @@ export enum ValueKind {
21
22
  Lambda = 7,
22
23
  }
23
24
 
24
- /** Result envelope returned by every fallible binding call. */
25
+ /** Status carried by binding result envelopes. Argument validation may
26
+ * throw `TypeError` or `RangeError` before returning a result. */
25
27
  export interface Status {
26
28
  /** True when the underlying C ABI returned `kOk`. */
27
29
  ok: boolean;
@@ -165,10 +167,20 @@ export enum WorkbookFormat {
165
167
  Xlsb = 2,
166
168
  }
167
169
 
168
- /** Return type of `Workbook.sheetName(idx)`. */
169
- export interface StringResult {
170
+ /** `{ status, value }` returned by the text accessors (`sheetName`,
171
+ * `localizeFunctionName`, `excelProfileId`, ...). `value` is `""` on
172
+ * failure. */
173
+ export interface StringResult<T extends string = string> {
170
174
  status: Status;
171
- value: string;
175
+ value: T;
176
+ }
177
+
178
+ /** `{ status, value }` returned by the numeric accessors (every `*Count`,
179
+ * `calcMode`, ...). `value` is `0` on failure, so a zero count is only
180
+ * meaningful when `status.ok` is true. */
181
+ export interface NumberResult<T extends number = number> {
182
+ status: Status;
183
+ value: T;
172
184
  }
173
185
 
174
186
  /** Return type of `Workbook.cellAt(sheet, idx)`. */
@@ -255,7 +267,7 @@ export interface PivotCell {
255
267
  depth: number;
256
268
  /** Source field name when known. */
257
269
  fieldName: string;
258
- /** Excel number-format code when known. */
270
+ /** The data field's `numFmtId` as a decimal string; empty when unset. */
259
271
  numberFormat: string;
260
272
  }
261
273
 
@@ -334,13 +346,16 @@ export enum PivotFilterType {
334
346
  LabelDate = 5,
335
347
  }
336
348
 
337
- /** Date-grouping granularity. Mirrors `fm_pivot_date_grouping_t`. */
349
+ /** Date-grouping granularity. Mirrors `fm_pivot_date_grouping_t`.
350
+ * `Days` is Excel's "By: Days" grouping (an explicit interval, e.g. a
351
+ * real Excel "week" is `Days` with `intervalDays: 7`); there is no
352
+ * separate week granularity. */
338
353
  export enum PivotDateGrouping {
339
354
  Day = 0,
340
355
  Month = 1,
341
356
  Quarter = 2,
342
357
  Year = 3,
343
- Week = 4,
358
+ Days = 4,
344
359
  Hour = 5,
345
360
  Minute = 6,
346
361
  Second = 7,
@@ -398,6 +413,7 @@ export interface PivotFieldSpec {
398
413
  customName?: string;
399
414
  axis: PivotAxis;
400
415
  subtotalTop?: boolean;
416
+ /** `numFmtId` as a decimal string (built-in or from `addNumFmt`). */
401
417
  numberFormat?: string;
402
418
  }
403
419
 
@@ -408,6 +424,7 @@ export interface PivotDataFieldSpec {
408
424
  name: string;
409
425
  fieldIndex: number;
410
426
  aggregation: PivotAggregation;
427
+ /** `numFmtId` as a decimal string (built-in or from `addNumFmt`). */
411
428
  numberFormat?: string;
412
429
  showAs?: PivotShowValuesAs;
413
430
  showAsBaseField?: number;
@@ -519,6 +536,13 @@ export interface CivilTime {
519
536
  second: number;
520
537
  }
521
538
 
539
+ /** Return type of `Workbook.pinnedNow()`. `now` is `null` when the workbook
540
+ * follows the host clock, and on failure. */
541
+ export interface PinnedNowResult {
542
+ status: Status;
543
+ now: CivilTime | null;
544
+ }
545
+
522
546
  /** RGBA colour. Channels are 0-255 (sRGB). */
523
547
  export interface CfColor {
524
548
  r: number;
@@ -554,6 +578,9 @@ export interface CfMatch {
554
578
  barBorderEngaged: number;
555
579
  barBorder: CfColor;
556
580
  barGradient: number;
581
+ /** The rule's direction (0 = context, 1 = left to right, 2 = right to
582
+ * left); the bar geometry is stated from the left edge. */
583
+ barDirection: number;
557
584
  /** Active when `kind === IconSet`; ordinal of `formulon::cf::IconSetName`. */
558
585
  iconSetName: number;
559
586
  iconIndex: number;
@@ -584,6 +611,161 @@ export interface PaginationResult {
584
611
  horizontalBreaks: number[];
585
612
  verticalBreaks: number[];
586
613
  pageCount: number;
614
+ /** Paper the layout ran on, after the orientation swap. `known` is false
615
+ * when the stored `paperSize` was unrecognised and A4 was substituted. */
616
+ paper: PaginationPaper;
617
+ margins: PaginationMargins;
618
+ /** Cell-body rectangle before print-title reservation, from the page's top-left corner. */
619
+ printable: RectPt;
620
+ /** Effective scale as a factor (1 is 100%). */
621
+ scale: number;
622
+ /** 0 = down then over, 1 = over then down. */
623
+ pageOrder: number;
624
+ /** Repeat rows / columns in effect (0-based, inclusive); a span is meaningful only when its flag is set. */
625
+ printTitles: PaginationPrintTitles;
626
+ /** Physical pages in print order. */
627
+ pages: PaginationPage[];
628
+ /** Parallel to `horizontalBreaks`: true for a manual break. */
629
+ horizontalBreakManual: boolean[];
630
+ /** Parallel to `verticalBreaks`: true for a manual break. */
631
+ verticalBreakManual: boolean[];
632
+ }
633
+
634
+ /** `PaginationResult.paper`. `known` is false when the stored `paperSize` was
635
+ * unrecognised and A4 was substituted. */
636
+ export interface PaginationPaper {
637
+ widthPt: number;
638
+ heightPt: number;
639
+ landscape: boolean;
640
+ known: boolean;
641
+ }
642
+
643
+ /** `PaginationResult.margins`, in points; `header` / `footer` are measured
644
+ * from the page edge to the header / footer band. */
645
+ export interface PaginationMargins {
646
+ left: number;
647
+ right: number;
648
+ top: number;
649
+ bottom: number;
650
+ header: number;
651
+ footer: number;
652
+ }
653
+
654
+ /** `PaginationResult.printTitles`: repeat rows / columns (0-based,
655
+ * inclusive). A span is meaningful only when its `has*` flag is true. */
656
+ export interface PaginationPrintTitles {
657
+ hasRows: boolean;
658
+ firstRow: number;
659
+ lastRow: number;
660
+ hasCols: boolean;
661
+ firstCol: number;
662
+ lastCol: number;
663
+ }
664
+
665
+ /** A rectangle in points. */
666
+ export interface RectPt {
667
+ x: number;
668
+ y: number;
669
+ width: number;
670
+ height: number;
671
+ }
672
+
673
+ /** One physical page of a `PaginationResult`. `widthPt` / `heightPt` are the
674
+ * scaled extent of the page's own cell block (repeated titles excluded) and
675
+ * `originXPt` / `originYPt` is that block's top-left corner on the paper. */
676
+ export interface PaginationPage {
677
+ /** Index into `PaginationResult.printArea` (0 for the used-range fallback). */
678
+ areaIndex: number;
679
+ firstRow: number;
680
+ lastRow: number;
681
+ firstCol: number;
682
+ lastCol: number;
683
+ originXPt: number;
684
+ originYPt: number;
685
+ widthPt: number;
686
+ heightPt: number;
687
+ }
688
+
689
+ /** Which Windows column-width figure a geometry call uses. Mirrors `fm_geometry_mode_t`.
690
+ * `Display` is the screen figure (`Range.Width` at 96 DPI); `Print` is the
691
+ * DPI-stable figure pagination breaks on. Row heights are identical in both. */
692
+ export enum GeometryMode {
693
+ Display = 0,
694
+ Print = 1,
695
+ }
696
+
697
+ /** Return type of `Workbook.getCellRectPt(...)`. */
698
+ export interface CellRectResult extends RectPt {
699
+ status: Status;
700
+ }
701
+
702
+ /** Return type of `Workbook.getWidthModel(...)`. */
703
+ export interface WidthModelResult {
704
+ status: Status;
705
+ pointsPerChar: number;
706
+ paddingPt: number;
707
+ normalFontSize: number;
708
+ /** False when the Normal font is not a measured calibration point and the Calibri 11 figure was extrapolated. */
709
+ calibrated: boolean;
710
+ normalFontName: string;
711
+ platform: string;
712
+ }
713
+
714
+ /** Sheet default column / row metrics (`<sheetFormatPr>`). A width / height is
715
+ * meaningful only when its `has*` flag is set. */
716
+ export interface SheetFormatDefaults {
717
+ /** Character units. */
718
+ defaultColWidth: number;
719
+ /** Points. */
720
+ defaultRowHeight: number;
721
+ /** Character units; OOXML default 8. */
722
+ baseColWidth: number;
723
+ hasDefaultColWidth: boolean;
724
+ hasDefaultRowHeight: boolean;
725
+ }
726
+
727
+ /** Return type of `Workbook.getSheetFormatDefaults(sheet)`. */
728
+ export interface SheetFormatDefaultsResult extends SheetFormatDefaults {
729
+ status: Status;
730
+ }
731
+
732
+ /** Return type of `Workbook.getFormula` / `getFormulaR1C1`. `formula` is `null` when the cell holds no formula. */
733
+ export interface FormulaResult {
734
+ status: Status;
735
+ formula: string | null;
736
+ }
737
+
738
+ /** One populated cell of `Workbook.getCellsInRange`. */
739
+ export interface RangeCell {
740
+ row: number;
741
+ col: number;
742
+ formula: string | null;
743
+ value: Value;
744
+ }
745
+
746
+ /** Return type of `Workbook.getCellsInRange(...)`. */
747
+ export interface CellsInRangeResult {
748
+ status: Status;
749
+ cells: RangeCell[];
750
+ /** Resume position for the next page, or `null` when the range is exhausted. */
751
+ nextCursor: number | null;
752
+ }
753
+
754
+ /** Outcome of a display-text rendering. Mirrors `fm_display_status_t`.
755
+ * `Overflow`: the value cannot be shown in the format and the text is
756
+ * `########`. `InvalidFormat`: the code is malformed and the text is the
757
+ * General rendering. */
758
+ export enum DisplayStatus {
759
+ Ok = 0,
760
+ Overflow = 1,
761
+ InvalidFormat = 2,
762
+ }
763
+
764
+ /** Return type of `Workbook.getDisplayText` / `formatValue`. */
765
+ export interface DisplayTextResult {
766
+ status: Status;
767
+ text: string;
768
+ displayStatus: DisplayStatus;
587
769
  }
588
770
 
589
771
  /** Sheet tab visibility, mirroring OOXML `<sheet state>`.
@@ -709,6 +891,10 @@ export interface RowLayout {
709
891
  /** Whether OOXML customFormat=1 makes the row style effective. */
710
892
  hasStyle: number;
711
893
  styleXf: number;
894
+ /** Boolean stored as 0/1: whether a height is stored; `height` is meaningful only then. */
895
+ hasHeight: number;
896
+ /** Boolean stored as 0/1: an explicit override (`customHeight="1"`) rather than an auto height Excel recomputes. */
897
+ customHeight: number;
712
898
  }
713
899
 
714
900
  /** Return type of `Workbook.getSheetRowOverrides(sheet)`. */
@@ -781,13 +967,13 @@ export interface DataValidationRange {
781
967
  * * `op` — 0 between, 1 notBetween, 2 equal, 3 notEqual,
782
968
  * 4 greaterThan, 5 lessThan,
783
969
  * 6 greaterThanOrEqual, 7 lessThanOrEqual.
784
- * * `errorStyle` — 0 stop, 1 warning, 2 information.
970
+ * * `errorStyle` — a `ValidationErrorStyle`.
785
971
  */
786
972
  export interface DataValidationEntry {
787
973
  readonly ranges: ReadonlyArray<DataValidationRange>;
788
974
  readonly type: number;
789
975
  readonly op: number;
790
- readonly errorStyle: number;
976
+ readonly errorStyle: ValidationErrorStyle;
791
977
  readonly allowBlank: boolean;
792
978
  readonly showInputMessage: boolean;
793
979
  readonly showErrorMessage: boolean;
@@ -811,7 +997,7 @@ export interface DataValidationInput {
811
997
  ranges?: ReadonlyArray<DataValidationRange>;
812
998
  type: number;
813
999
  op?: number;
814
- errorStyle?: number;
1000
+ errorStyle?: ValidationErrorStyle;
815
1001
  allowBlank?: boolean;
816
1002
  showInputMessage?: boolean;
817
1003
  showErrorMessage?: boolean;
@@ -919,8 +1105,10 @@ export function mergeFunctionMetadata(
919
1105
  /** Signature of {@link mergeFunctionMetadata}. */
920
1106
  export type MergeFunctionMetadata = typeof mergeFunctionMetadata;
921
1107
 
922
- /** Spill region info returned by `spillInfo(sheet, row, col)`. */
1108
+ /** Spill region info returned by `spillInfo(sheet, row, col)`. On failure
1109
+ * `engaged` is `false` and the other fields are zero. */
923
1110
  export interface SpillInfo {
1111
+ readonly status: Status;
924
1112
  readonly engaged: boolean;
925
1113
  readonly anchorRow: number;
926
1114
  readonly anchorCol: number;
@@ -1002,6 +1190,9 @@ export interface ConditionalFormatEntry {
1002
1190
  readonly border?: CfColor;
1003
1191
  readonly negativeBorder?: CfColor;
1004
1192
  readonly axisColor?: CfColor;
1193
+ /** Edge the bar grows from: 0 = context (the sheet's reading
1194
+ * direction), 1 = left to right, 2 = right to left. */
1195
+ readonly direction: number;
1005
1196
  };
1006
1197
  /** Engaged for `iconSet` rules. */
1007
1198
  readonly iconSet?: {
@@ -1013,6 +1204,9 @@ export interface ConditionalFormatEntry {
1013
1204
  * and save but never consulted during evaluation. Each threshold
1014
1205
  * carries its own `type`, and that type is what interprets it. */
1015
1206
  readonly percent: boolean;
1207
+ /** Lower bound of the lowest icon's bucket; a cell below it gets no
1208
+ * icon. Always present on a rule read back from a workbook. */
1209
+ readonly floor?: CfValueObjectInput;
1016
1210
  };
1017
1211
  }
1018
1212
 
@@ -1064,6 +1258,8 @@ export interface ConditionalFormatInput {
1064
1258
  border?: CfColor;
1065
1259
  negativeBorder?: CfColor;
1066
1260
  axisColor?: CfColor;
1261
+ /** 0 = context (default), 1 = left to right, 2 = right to left. */
1262
+ direction?: number;
1067
1263
  };
1068
1264
  /** Payload for type 4 (`iconSet`). `name` is `formulon::cf::IconSetName` ordinal. */
1069
1265
  iconSet?: {
@@ -1075,6 +1271,9 @@ export interface ConditionalFormatInput {
1075
1271
  * consulted during evaluation (each threshold's own `type` is
1076
1272
  * authoritative). */
1077
1273
  percent?: boolean;
1274
+ /** Lower bound of the lowest icon's bucket; a cell below it gets no
1275
+ * icon. Omit for Excel's default, `percent 0`. */
1276
+ floor?: CfValueObjectInput;
1078
1277
  };
1079
1278
  }
1080
1279
 
@@ -1106,6 +1305,21 @@ export interface CellXfResult {
1106
1305
  hasWrapText: boolean;
1107
1306
  /** Whether `justifyLastLine="..."` was explicitly present. */
1108
1307
  hasJustifyLastLine: boolean;
1308
+ /** OOXML `applyNumberFormat` / `applyFont` / `applyFill` / `applyBorder` /
1309
+ * `applyAlignment` / `applyProtection`: whether this record's value for
1310
+ * the group overrides its parent named style. */
1311
+ applyNumberFormat: boolean;
1312
+ applyFont: boolean;
1313
+ applyFill: boolean;
1314
+ applyBorder: boolean;
1315
+ applyAlignment: boolean;
1316
+ applyProtection: boolean;
1317
+ /** OOXML `quotePrefix`. */
1318
+ quotePrefix: boolean;
1319
+ /** Whether the record carries a `<protection>` child. When false, `locked` / `hidden` are the model defaults (true / false). */
1320
+ hasProtection: boolean;
1321
+ locked: boolean;
1322
+ hidden: boolean;
1109
1323
  /** OOXML `textRotation`; present only when the source attribute existed. */
1110
1324
  textRotation?: number;
1111
1325
  /** OOXML `indent`; present only when the source attribute existed. */
@@ -1132,7 +1346,7 @@ export interface CellXfResult {
1132
1346
  * the writer emits the sibling `*Argb` as `rgb`. */
1133
1347
  export interface ColorSpec {
1134
1348
  /** 0=none, 1=rgb, 2=theme, 3=indexed, 4=auto. */
1135
- kind: number;
1349
+ kind: FilterKind;
1136
1350
  /** AARRGGBB; meaningful when `kind` is 1. */
1137
1351
  rgb: number;
1138
1352
  /** Theme index; meaningful when `kind` is 2. */
@@ -1239,6 +1453,21 @@ export interface CellXf {
1239
1453
  hasWrapText?: boolean;
1240
1454
  /** Whether `justifyLastLine` was explicitly supplied; defaults to inference. */
1241
1455
  hasJustifyLastLine?: boolean;
1456
+ /** OOXML `apply*` flags; each defaults to false. */
1457
+ applyNumberFormat?: boolean;
1458
+ applyFont?: boolean;
1459
+ applyFill?: boolean;
1460
+ applyBorder?: boolean;
1461
+ applyAlignment?: boolean;
1462
+ applyProtection?: boolean;
1463
+ /** OOXML `quotePrefix`; defaults to false. */
1464
+ quotePrefix?: boolean;
1465
+ /** Whether to write a `<protection>` child. Omit to infer from `locked` / `hidden`. */
1466
+ hasProtection?: boolean;
1467
+ /** Defaults to true; ignored unless the record carries a `<protection>` child. */
1468
+ locked?: boolean;
1469
+ /** Defaults to false; ignored unless the record carries a `<protection>` child. */
1470
+ hidden?: boolean;
1242
1471
  /** OOXML `textRotation` (0..180 or 255). Omitted when absent. */
1243
1472
  textRotation?: number;
1244
1473
  /** OOXML `indent` (0..255). Omitted when absent. */
@@ -1381,7 +1610,235 @@ export interface ExternalLinkRecord {
1381
1610
  * `TargetMode="External"` (the common case). */
1382
1611
  targetExternal: boolean;
1383
1612
  /** One of `ExternalLinkKind.*`. */
1384
- kind: number;
1613
+ kind: FilterKind;
1614
+ }
1615
+
1616
+ /** Argument of `Workbook.setCellStyle`. Mirrors `CellStyleResult` without the status. */
1617
+ export interface CellStyleRecord {
1618
+ /** Display name of the style. */
1619
+ name: string;
1620
+ /** Index into the `<cellStyleXfs>` table; defaults to 0. */
1621
+ xfId?: number;
1622
+ /** OOXML built-in ordinal (`0..53`); defaults to `0xFFFFFFFF` (custom). */
1623
+ builtinId?: number;
1624
+ /** Outline level of the `RowLevel_n` / `ColLevel_n` styles; defaults to 0. */
1625
+ iLevel?: number;
1626
+ hidden?: boolean;
1627
+ customBuiltin?: boolean;
1628
+ }
1629
+
1630
+ /** Criterion of an AutoFilter column. Mirrors `fm_filter_kind_t`. */
1631
+ export enum FilterKind {
1632
+ None = 0,
1633
+ Values = 1,
1634
+ Custom = 2,
1635
+ Top10 = 3,
1636
+ Dynamic = 4,
1637
+ Color = 5,
1638
+ Icon = 6,
1639
+ }
1640
+
1641
+ /** Comparison operator of a custom AutoFilter condition. Mirrors `fm_filter_operator_t`. */
1642
+ export enum FilterOperator {
1643
+ Equal = 0,
1644
+ LessThan = 1,
1645
+ LessThanOrEqual = 2,
1646
+ NotEqual = 3,
1647
+ GreaterThanOrEqual = 4,
1648
+ GreaterThan = 5,
1649
+ }
1650
+
1651
+ /** Dynamic AutoFilter type, in `ST_DynamicFilterType` schema order. Mirrors `fm_dynamic_filter_type_t`. */
1652
+ export enum DynamicFilterType {
1653
+ Null = 0,
1654
+ AboveAverage = 1,
1655
+ BelowAverage = 2,
1656
+ Tomorrow = 3,
1657
+ Today = 4,
1658
+ Yesterday = 5,
1659
+ NextWeek = 6,
1660
+ ThisWeek = 7,
1661
+ LastWeek = 8,
1662
+ NextMonth = 9,
1663
+ ThisMonth = 10,
1664
+ LastMonth = 11,
1665
+ NextQuarter = 12,
1666
+ ThisQuarter = 13,
1667
+ LastQuarter = 14,
1668
+ NextYear = 15,
1669
+ ThisYear = 16,
1670
+ LastYear = 17,
1671
+ YearToDate = 18,
1672
+ Q1 = 19,
1673
+ Q2 = 20,
1674
+ Q3 = 21,
1675
+ Q4 = 22,
1676
+ M1 = 23,
1677
+ M2 = 24,
1678
+ M3 = 25,
1679
+ M4 = 26,
1680
+ M5 = 27,
1681
+ M6 = 28,
1682
+ M7 = 29,
1683
+ M8 = 30,
1684
+ M9 = 31,
1685
+ M10 = 32,
1686
+ M11 = 33,
1687
+ M12 = 34,
1688
+ }
1689
+
1690
+ /** What a sort condition sorts by. Mirrors `fm_sort_by_t`. */
1691
+ export enum SortBy {
1692
+ Value = 0,
1693
+ CellColor = 1,
1694
+ FontColor = 2,
1695
+ Icon = 3,
1696
+ }
1697
+
1698
+ /** Sort method of an AutoFilter sort state. Mirrors `fm_sort_method_t`. */
1699
+ export enum SortMethod {
1700
+ None = 0,
1701
+ PinYin = 1,
1702
+ Stroke = 2,
1703
+ }
1704
+
1705
+ /** Granularity of an AutoFilter date-group item. Mirrors `fm_date_time_grouping_t`. */
1706
+ export enum DateTimeGrouping {
1707
+ Year = 0,
1708
+ Month = 1,
1709
+ Day = 2,
1710
+ Hour = 3,
1711
+ Minute = 4,
1712
+ Second = 5,
1713
+ }
1714
+
1715
+ /** Data-validation error style. Mirrors `fm_validation_error_style_t`. */
1716
+ export enum ValidationErrorStyle {
1717
+ Stop = 0,
1718
+ Warning = 1,
1719
+ Information = 2,
1720
+ }
1721
+
1722
+ /** Where a colour is used; decides what an automatic colour means. Mirrors `fm_color_context_t`. */
1723
+ export enum ColorContext {
1724
+ Font = 0,
1725
+ FillForeground = 1,
1726
+ FillBackground = 2,
1727
+ Border = 3,
1728
+ }
1729
+
1730
+ /** Raster format of an image; `Unknown` marks "no image bytes found". Mirrors `fm_image_format_t`. */
1731
+ export enum ImageFormat {
1732
+ Unknown = 0,
1733
+ Png = 1,
1734
+ Jpeg = 2,
1735
+ Gif = 3,
1736
+ Bmp = 4,
1737
+ }
1738
+
1739
+ /** What a drawing anchor holds. Mirrors `fm_drawing_object_kind_t`. */
1740
+ export enum DrawingObjectKind {
1741
+ Picture = 0,
1742
+ Shape = 1,
1743
+ Chart = 2,
1744
+ Group = 3,
1745
+ Connector = 4,
1746
+ GraphicFrame = 5,
1747
+ Other = 6,
1748
+ }
1749
+
1750
+ /** The anchor element type of a drawing object. Mirrors `fm_anchor_kind_t`. */
1751
+ export enum AnchorKind {
1752
+ OneCell = 0,
1753
+ TwoCell = 1,
1754
+ Absolute = 2,
1755
+ }
1756
+
1757
+ /** How a drawing object follows row and column edits. Mirrors `fm_anchor_edit_as_t`. */
1758
+ export enum AnchorEditAs {
1759
+ TwoCell = 0,
1760
+ OneCell = 1,
1761
+ Absolute = 2,
1762
+ }
1763
+
1764
+ /** How a colour was resolved. Mirrors `fm_color_resolution_t`. `Exact` is a literal or workbook-supplied
1765
+ * colour; `DefaultTheme` / `ThemeUnparseable` mean the default (Office 2013-2022) theme was used because
1766
+ * the theme part is absent / unparseable; `IndexOutOfRange` is black; `AutoContext` is an automatic colour
1767
+ * (black for font and border, white for fills). */
1768
+ export enum ColorResolution {
1769
+ Exact = 0,
1770
+ DefaultTheme = 1,
1771
+ IndexOutOfRange = 2,
1772
+ ThemeUnparseable = 3,
1773
+ AutoContext = 4,
1774
+ }
1775
+
1776
+ /** Where `getTheme` read the theme from. Mirrors the C `out_source` values. */
1777
+ export enum ThemeSource {
1778
+ Part = 0,
1779
+ Default = 1,
1780
+ Unparseable = 2,
1781
+ }
1782
+
1783
+ /** Where `getEffectiveStyle` took its xf from. */
1784
+ export enum EffectiveStyleSource {
1785
+ Cell = 0,
1786
+ Row = 1,
1787
+ Column = 2,
1788
+ Default = 3,
1789
+ }
1790
+
1791
+ /** The theme's typefaces; `*EastAsian` is the `a:ea` face, else the `Jpan` script face. */
1792
+ export interface ThemeFonts {
1793
+ majorLatin: string;
1794
+ majorEastAsian: string;
1795
+ minorLatin: string;
1796
+ minorEastAsian: string;
1797
+ }
1798
+
1799
+ /** Return type of `Workbook.getTheme()`. */
1800
+ export interface ThemeResult {
1801
+ status: Status;
1802
+ /** One of `ThemeSource.*`. */
1803
+ source: ThemeSource;
1804
+ /** 0xFFRRGGBB in `clrScheme` order: dk1, lt1, dk2, lt2, accent1..6, hlink, folHlink. */
1805
+ colors: number[];
1806
+ fonts: ThemeFonts;
1807
+ }
1808
+
1809
+ /** A resolved colour: 0xFFRRGGBB plus how it was obtained. */
1810
+ export interface ResolvedColor {
1811
+ argb: number;
1812
+ resolution: ColorResolution;
1813
+ }
1814
+
1815
+ /** Return type of `Workbook.resolveColor(...)`. */
1816
+ export interface ResolvedColorResult extends ResolvedColor {
1817
+ status: Status;
1818
+ }
1819
+
1820
+ /** Return type of `Workbook.getEffectiveStyle(...)`. */
1821
+ export interface EffectiveStyleResult {
1822
+ status: Status;
1823
+ xfIndex: number;
1824
+ /** One of `EffectiveStyleSource.*`. */
1825
+ source: EffectiveStyleSource;
1826
+ fontIndex: number;
1827
+ fillIndex: number;
1828
+ borderIndex: number;
1829
+ font: ResolvedColor;
1830
+ fillForeground: ResolvedColor;
1831
+ fillBackground: ResolvedColor;
1832
+ borders: {
1833
+ left: ResolvedColor;
1834
+ right: ResolvedColor;
1835
+ top: ResolvedColor;
1836
+ bottom: ResolvedColor;
1837
+ diagonal: ResolvedColor;
1838
+ };
1839
+ locked: boolean;
1840
+ hidden: boolean;
1841
+ numFmtCode: string;
1385
1842
  }
1386
1843
 
1387
1844
  /** Return type of `Workbook.getCellStyle(index)`. Mirrors
@@ -1453,6 +1910,226 @@ export interface SheetAutoFilterXmlResult {
1453
1910
  xml: string;
1454
1911
  }
1455
1912
 
1913
+ /** One `<dateGroupItem>` of a values filter. `grouping` is the granularity
1914
+ * the item matches at (a `DateTimeGrouping`); fields finer than `grouping` are zero. */
1915
+ export interface AutoFilterDateGroup {
1916
+ year: number;
1917
+ month: number;
1918
+ day: number;
1919
+ hour: number;
1920
+ minute: number;
1921
+ second: number;
1922
+ grouping: DateTimeGrouping;
1923
+ }
1924
+
1925
+ /** One `<filterColumn>`. `colId` is the 0-based offset from the first column
1926
+ * of the AutoFilter range. `kind` selects the criterion and only that
1927
+ * criterion's fields are read on input (a `FilterKind`); on output every other criterion's
1928
+ * fields are zero. Custom operators `op1` / `op2` are
1929
+ * `FilterOperator`s; `dynamicType` is a `DynamicFilterType`.
1930
+ * `dxfId` of `4294967295` means absent. `iconSet` is the conditional-format
1931
+ * icon-set ordinal. Omitted input fields read as zero / false / empty,
1932
+ * except `showButton` (true) and `dxfId` (absent). */
1933
+ export interface AutoFilterColumn {
1934
+ colId: number;
1935
+ hiddenButton: boolean;
1936
+ showButton: boolean;
1937
+ kind: FilterKind;
1938
+ filterBlank: boolean;
1939
+ values: string[];
1940
+ dateGroups: AutoFilterDateGroup[];
1941
+ customAnd: boolean;
1942
+ customCount: number;
1943
+ op1: FilterOperator;
1944
+ val1: string;
1945
+ op2: FilterOperator;
1946
+ val2: string;
1947
+ top: boolean;
1948
+ percent: boolean;
1949
+ hasFilterVal: boolean;
1950
+ topVal: number;
1951
+ filterVal: number;
1952
+ dynamicType: DynamicFilterType;
1953
+ hasDynVal: boolean;
1954
+ hasDynMaxVal: boolean;
1955
+ dynVal: number;
1956
+ dynMaxVal: number;
1957
+ valIso: string;
1958
+ maxValIso: string;
1959
+ dxfId: number;
1960
+ cellColor: boolean;
1961
+ iconSet: number;
1962
+ iconId: number;
1963
+ hasIconId: boolean;
1964
+ }
1965
+
1966
+ /** One `<sortCondition>`. `sortBy` is a `SortBy`. `dxfId` is read only when `hasDxfId`, `iconId` only when
1967
+ * `hasIconId`. */
1968
+ export interface AutoFilterSortCondition {
1969
+ ref: MergeRange;
1970
+ descending: boolean;
1971
+ sortBy: SortBy;
1972
+ customList: string;
1973
+ dxfId: number;
1974
+ hasDxfId: boolean;
1975
+ iconSet: number;
1976
+ iconId: number;
1977
+ hasIconId: boolean;
1978
+ }
1979
+
1980
+ /** The `<sortState>` of an AutoFilter. `sortMethod` is a
1981
+ * `SortMethod`. */
1982
+ export interface AutoFilterSortState {
1983
+ ref: MergeRange;
1984
+ columnSort: boolean;
1985
+ caseSensitive: boolean;
1986
+ sortMethod: SortMethod;
1987
+ conditions: AutoFilterSortCondition[];
1988
+ }
1989
+
1990
+ /** A sheet or table AutoFilter. `range` includes the header row; `columns`
1991
+ * must be in strictly ascending `colId` order inside it. */
1992
+ export interface AutoFilter {
1993
+ range: MergeRange;
1994
+ columns: AutoFilterColumn[];
1995
+ sort: AutoFilterSortState | null;
1996
+ }
1997
+
1998
+ /** Result of `Workbook.getAutoFilter` / `getTableAutoFilter`. `autoFilter` is
1999
+ * `null` when there is none. */
2000
+ export interface AutoFilterResult {
2001
+ status: Status;
2002
+ autoFilter: AutoFilter | null;
2003
+ }
2004
+
2005
+ /** Result of `Workbook.evaluateAutoFilter` / `evaluateTableAutoFilter`.
2006
+ * `match[i]` tells whether body row `firstRow + i` satisfies the criteria. */
2007
+ export interface AutoFilterEvalResult {
2008
+ status: Status;
2009
+ firstRow: number;
2010
+ match: boolean[];
2011
+ }
2012
+
2013
+ /** Result of `Workbook.validateValue`. `hasRule` is false when no rule covers
2014
+ * the cell, and `valid` is then true. Otherwise `ruleIndex` indexes
2015
+ * `getValidations` and `errorStyle` is a `ValidationErrorStyle`. */
2016
+ export interface ValidationOutcomeResult {
2017
+ status: Status;
2018
+ hasRule: boolean;
2019
+ valid: boolean;
2020
+ ruleIndex: number;
2021
+ errorStyle: ValidationErrorStyle;
2022
+ }
2023
+
2024
+ /** One `@person` mention in a threaded comment's text; `start` and `length`
2025
+ * are in UTF-16 code units. */
2026
+ export interface Mention {
2027
+ personId: string;
2028
+ mentionId: string;
2029
+ start: number;
2030
+ length: number;
2031
+ }
2032
+
2033
+ /** One threaded comment: a thread's opening comment, or a reply when
2034
+ * `parentId` is non-empty. Ids are brace-wrapped uppercase GUIDs and
2035
+ * `created` is `YYYY-MM-DDTHH:MM:SS.ss`; the caller supplies both. `done`
2036
+ * is the thread's resolved state, meaningful on the opening comment only. */
2037
+ export interface ThreadedComment {
2038
+ id: string;
2039
+ row: number;
2040
+ col: number;
2041
+ personId: string;
2042
+ created: string;
2043
+ text: string;
2044
+ parentId: string;
2045
+ done: boolean;
2046
+ mentions: Mention[];
2047
+ }
2048
+
2049
+ /** One entry of the workbook's person list. */
2050
+ export interface Person {
2051
+ id: string;
2052
+ displayName: string;
2053
+ userId: string;
2054
+ providerId: string;
2055
+ }
2056
+
2057
+ /** Result of `Workbook.getThreadedComments`, in file order: each thread's
2058
+ * opening comment followed by its replies. */
2059
+ export interface ThreadedCommentsResult {
2060
+ status: Status;
2061
+ comments: ThreadedComment[];
2062
+ }
2063
+
2064
+ /** Result of `Workbook.getPersons`. */
2065
+ export interface PersonsResult {
2066
+ status: Status;
2067
+ persons: Person[];
2068
+ }
2069
+
2070
+ /** Format and pixel size of an image; zeroed when `status` is not ok. */
2071
+ export interface ImageInfoResult {
2072
+ status: Status;
2073
+ format: ImageFormat;
2074
+ pxWidth: number;
2075
+ pxHeight: number;
2076
+ }
2077
+
2078
+ /** Result of `Workbook.getImage`. `bytes` is a copy, empty on failure. */
2079
+ export interface ImageResult extends ImageInfoResult {
2080
+ bytes: Uint8Array;
2081
+ }
2082
+
2083
+ /** One anchored object of a sheet's drawing. An absolute anchor reports its
2084
+ * position from A1 as `fromColOff` (x) and `fromRowOff` (y); `toRow` /
2085
+ * `toCol` and their offsets are zero unless the anchor is two-cell. Offsets
2086
+ * and `cx` / `cy` are in EMU. `imageFormat` is non-zero for a picture whose
2087
+ * media part is present; `mediaPath` is empty for a non-picture. */
2088
+ export interface DrawingObject {
2089
+ objectId: number;
2090
+ kind: DrawingObjectKind;
2091
+ anchorKind: AnchorKind;
2092
+ editAs: AnchorEditAs;
2093
+ fromRow: number;
2094
+ fromCol: number;
2095
+ fromRowOff: number;
2096
+ fromColOff: number;
2097
+ toRow: number;
2098
+ toCol: number;
2099
+ toRowOff: number;
2100
+ toColOff: number;
2101
+ cx: number;
2102
+ cy: number;
2103
+ imageFormat: ImageFormat;
2104
+ name: string;
2105
+ descr: string;
2106
+ mediaPath: string;
2107
+ }
2108
+
2109
+ /** Placement of an inserted image. `anchorKind` is `OneCell` (default) or
2110
+ * `TwoCell`; `editAs` applies to a two-cell anchor only. `row` / `col` is
2111
+ * the 0-based top-left cell and `rowOffEmu` / `colOffEmu` the offset inside
2112
+ * it. A zero `widthEmu` / `heightEmu` means the pixel size times 9525. An
2113
+ * empty `name` becomes `Picture <id>`. */
2114
+ export interface ImageInsertOptions {
2115
+ name?: string;
2116
+ descr?: string;
2117
+ anchorKind?: AnchorKind;
2118
+ editAs?: AnchorEditAs;
2119
+ row?: number;
2120
+ col?: number;
2121
+ rowOffEmu?: number;
2122
+ colOffEmu?: number;
2123
+ widthEmu?: number;
2124
+ heightEmu?: number;
2125
+ }
2126
+
2127
+ /** Result of `Workbook.insertImage`; `objectId` is zero on failure. */
2128
+ export interface InsertImageResult {
2129
+ status: Status;
2130
+ objectId: number;
2131
+ }
2132
+
1456
2133
  /** Result of the five raw print-settings getters. The empty `xml` string
1457
2134
  * means the sheet declares no such element. */
1458
2135
  export interface SheetPrintXmlResult {
@@ -1617,7 +2294,10 @@ export type IterativeProgressCallback = (
1617
2294
  export interface Workbook {
1618
2295
  /** True when the wrapper holds a live native handle. */
1619
2296
  isValid(): boolean;
1620
- /** Releases the native handle. The instance must not be used afterwards. */
2297
+ /** Releases the native handle. The instance must not be used afterwards.
2298
+ * Throws, and leaves the handle intact, if called from inside this
2299
+ * workbook's own iterative-progress callback -- that callback is still
2300
+ * running a `recalc`/`recalcParallel` against the handle. */
1621
2301
  delete(): void;
1622
2302
 
1623
2303
  save(): SaveResult;
@@ -1634,12 +2314,15 @@ export interface Workbook {
1634
2314
  renameSheet(index: number, newName: string): Status;
1635
2315
  /** Moves the sheet from `fromIdx` to `toIdx` (post-removal index). */
1636
2316
  moveSheet(fromIdx: number, toIdx: number): Status;
1637
- sheetCount(): number;
2317
+ sheetCount(): NumberResult;
1638
2318
  sheetName(idx: number): StringResult;
1639
2319
 
1640
2320
  setNumber(sheet: number, row: number, col: number, value: number): Status;
1641
2321
  setBool(sheet: number, row: number, col: number, value: boolean): Status;
1642
- /** Stores a static Excel error literal; `errorCode` is an ErrorCode ordinal. */
2322
+ /** Stores a static Excel error literal; `errorCode` is an ErrorCode
2323
+ * ordinal. Unlike `setNumber`/`setBool`/`setText`, an omitted
2324
+ * `errorCode` has no sane zero-value default, so it is rejected
2325
+ * rather than silently writing error code 0 (`#NULL!`). */
1643
2326
  setError(sheet: number, row: number, col: number, errorCode: number): Status;
1644
2327
  setText(sheet: number, row: number, col: number, text: string): Status;
1645
2328
  /** Stores (or, when empty, clears) the cell's OOXML phonetic guide (`<rPh>`). */
@@ -1660,12 +2343,25 @@ export interface Workbook {
1660
2343
 
1661
2344
  getValue(sheet: number, row: number, col: number): CellResult;
1662
2345
 
2346
+ /** The stored A1 formula (leading `=` included), or `formula: null` for a cell that holds none. */
2347
+ getFormula(sheet: number, row: number, col: number): FormulaResult;
2348
+ /** The formula in R1C1 notation relative to the cell, without a leading `=`; `formula: null` when the cell holds none. */
2349
+ getFormulaR1C1(sheet: number, row: number, col: number): FormulaResult;
2350
+ /** One page of the populated cells (formula or non-blank value, spill phantoms included) inside
2351
+ * `range`, row-major. `cursor` is the `nextCursor` of the previous page (omit for the first);
2352
+ * `limit` caps the page (omit or 0 for the maximum, 65536). */
2353
+ getCellsInRange(sheet: number, range: MergeRange, cursor?: number | null, limit?: number | null): CellsInRangeResult;
2354
+ /** The text Excel displays for the cell, from its value and number format under the workbook's date system. */
2355
+ getDisplayText(sheet: number, row: number, col: number): DisplayTextResult;
2356
+ /** Renders `value` (blank, number, boolean, text or error) under the stored-form number format `formatCode`; empty means General. */
2357
+ formatValue(value: Value, formatCode: string): DisplayTextResult;
2358
+
1663
2359
  /** Evaluates `formula` as if entered at `(sheet, row, col)` and returns a
1664
2360
  * single scalar result, without mutating the workbook. Local and
1665
2361
  * cross-sheet references, defined names, and `ROW()` / `COLUMN()` resolve
1666
2362
  * relative to the anchor. An array / spill result is reduced to its
1667
- * top-left element (a pragmatic API shape, not Excel implicit
1668
- * intersection or spilling; multi-cell results are a Phase 2 follow-up).
2363
+ * top-left element (not Excel implicit intersection or spilling; use
2364
+ * `evaluateFormulaArray` for the whole multi-cell result).
1669
2365
  * Note: a self-reference reads the target cell's cached value rather than
1670
2366
  * raising `#REF!`, since the ad-hoc formula never joins the dep graph. */
1671
2367
  evaluateFormulaText(sheet: number, row: number, col: number, formula: string): EvalResult;
@@ -1723,6 +2419,9 @@ export interface Workbook {
1723
2419
  * through `Number.MAX_SAFE_INTEGER` (2^53 - 1).
1724
2420
  * As with `recalc`, a throwing `IterativeProgressCallback` is reported as
1725
2421
  * status 7003 with the counters left at zero.
2422
+ * Only `@libraz/formulon/threads` starts workers. The default
2423
+ * `@libraz/formulon` build has no pthreads, so the same pass runs
2424
+ * serially with `workerThreadsStarted` at 0.
1726
2425
  */
1727
2426
  recalcParallel(threadCount: number): ParallelRecalcResult;
1728
2427
  /** Recalculates only cells touched by the supplied viewport. Reports
@@ -1748,17 +2447,17 @@ export interface Workbook {
1748
2447
  /**
1749
2448
  * Workbook-level calc mode (Excel `<calcPr calcMode>` policy).
1750
2449
  *
1751
- * Returns one of `CalcMode` codes. The engine itself does NOT gate
2450
+ * `value` is one of the `CalcMode` codes. The engine itself does NOT gate
1752
2451
  * evaluation on this value — every `recalc()` call honours all dirty
1753
2452
  * cells. The mode is preserved as round-trip metadata and surfaced
1754
2453
  * here so the UI can mirror Excel's user-visible state.
1755
2454
  */
1756
- calcMode(): CalcMode;
2455
+ calcMode(): NumberResult<CalcMode>;
1757
2456
  setCalcMode(mode: CalcMode): Status;
1758
2457
 
1759
2458
  /**
1760
- * The workbook's pinned wall-clock reading, or `null` when it follows the
1761
- * host clock (the default).
2459
+ * The workbook's pinned wall-clock reading as `now`, or `now: null` when
2460
+ * it follows the host clock (the default).
1762
2461
  *
1763
2462
  * Pinning gives `NOW()`, `TODAY()` and the pivot relative-period filters
1764
2463
  * ("this month", "year to date", ...) one instant to agree on. Without a
@@ -1780,36 +2479,29 @@ export interface Workbook {
1780
2479
  * pin is a calendar instant, not a normalising constructor: a month of 13
1781
2480
  * is rejected rather than rolled into the next year.
1782
2481
  */
1783
- pinnedNow(): CivilTime | null;
2482
+ pinnedNow(): PinnedNowResult;
1784
2483
  setPinnedNow(year: number, month: number, day: number, hour: number, minute: number, second: number): Status;
1785
2484
  clearPinnedNow(): Status;
1786
2485
 
1787
2486
  /**
1788
2487
  * Full formula-behaviour profile id. Defaults to `win-365-ja_JP`.
1789
2488
  */
1790
- excelProfileId(): ExcelProfileId;
2489
+ excelProfileId(): StringResult<ExcelProfileId>;
1791
2490
  setExcelProfileId(profileId: ExcelProfileId): Status;
1792
2491
 
1793
2492
  /**
1794
2493
  * The four structural edits move every structure the engine models:
1795
2494
  * cells, formulas, merges, conditional-format ranges, validations,
1796
2495
  * hyperlinks, tables, print areas, manual breaks and the auto-filter
1797
- * range.
1798
- *
1799
- * They do not move coordinates held in worksheet content the engine
1800
- * keeps byte-verbatim because it does not model it — the worksheet
1801
- * `<extLst>` (the `x14` conditional-formatting block behind DataBar
1802
- * negative-fill / axis / gradient settings, sparkline groups, slicer
1803
- * anchors) and any unmodelled `<worksheet>` child kept so a save does
1804
- * not drop it. Those keep their pre-edit rectangles.
2496
+ * range. The ranges and formulas inside the worksheet `<extLst>` (the
2497
+ * `x14` conditional-formatting block, sparkline groups, `x14`
2498
+ * validations) move with them, as Excel moves them.
1805
2499
  *
1806
- * What that looks like in Excel differs per extension: it drops an
1807
- * `x14` entry whose range no longer matches the legacy rule it extends,
1808
- * so an extended DataBar quietly reverts to its legacy rendering, while
1809
- * a sparkline group keeps drawing and reads its source range from the
1810
- * wrong cells. Neither raises a status or a diagnostic counter. Re-author
1811
- * those extensions after editing rows or columns on a sheet that carries
1812
- * them.
2500
+ * They do not move an unmodelled `<worksheet>` child kept byte-verbatim
2501
+ * so a save does not drop it (a `<sortState>`, for one): a `ref` inside
2502
+ * it keeps its pre-edit rectangle, and nothing reports it. An insert also
2503
+ * does not copy the formatting of the row or column before it onto the
2504
+ * new one, which Excel does — a sparkline included.
1813
2505
  */
1814
2506
 
1815
2507
  /** Inserts `count` rows at `row` on `sheet` and rewrites cross-workbook
@@ -1823,10 +2515,10 @@ export interface Workbook {
1823
2515
  /** Deletes `count` columns starting at `col` on `sheet`. */
1824
2516
  deleteCols(sheet: number, col: number, count: number): Status;
1825
2517
 
1826
- cellCount(sheet: number): number;
2518
+ cellCount(sheet: number): NumberResult;
1827
2519
  cellAt(sheet: number, idx: number): CellEntry;
1828
2520
 
1829
- definedNameCount(): number;
2521
+ definedNameCount(): NumberResult;
1830
2522
  definedNameAt(idx: number): DefinedNameEntry;
1831
2523
  /** Adds, replaces, or (when `formula` is empty) removes a workbook-
1832
2524
  * scoped defined name. */
@@ -1835,7 +2527,7 @@ export interface Workbook {
1835
2527
  * or a sheet-local scope (0-based sheet index). */
1836
2528
  setDefinedNameScoped(name: string, formula: string, localSheetId: number): Status;
1837
2529
 
1838
- tableCount(): number;
2530
+ tableCount(): NumberResult;
1839
2531
  tableAt(idx: number): TableEntry;
1840
2532
  createTable(input: TableInput): AddStyleResult;
1841
2533
  /** Partially updates a table. Omitted fields preserve their current
@@ -1849,17 +2541,76 @@ export interface Workbook {
1849
2541
  /** Replaces the worksheet-level `<autoFilter>` XML fragment; empty clears it. */
1850
2542
  setSheetAutoFilterXml(sheet: number, xml: string): Status;
1851
2543
 
1852
- passthroughCount(): number;
2544
+ /** Reads the sheet's typed AutoFilter; `autoFilter` is `null` when absent. */
2545
+ getAutoFilter(sheet: number): AutoFilterResult;
2546
+ /** Replaces the sheet AutoFilter and its hidden `_xlnm._FilterDatabase`
2547
+ * name. Row visibility is unchanged; call `applyAutoFilter` to hide the
2548
+ * excluded rows. */
2549
+ setAutoFilter(sheet: number, filter: AutoFilter): Status;
2550
+ /** Removes the sheet AutoFilter. Row visibility is unchanged. */
2551
+ removeAutoFilter(sheet: number): Status;
2552
+ /** Hides every body row the criteria exclude and shows the rest, as
2553
+ * Excel's Reapply does. Fails with a not-found status when there is no AutoFilter. */
2554
+ applyAutoFilter(sheet: number): Status;
2555
+ /** Drops every column criterion and shows all body rows. */
2556
+ clearAutoFilter(sheet: number): Status;
2557
+ /** Evaluates the sheet AutoFilter without changing the sheet. */
2558
+ evaluateAutoFilter(sheet: number): AutoFilterEvalResult;
2559
+ /** Table counterparts, addressed by the workbook-wide table index
2560
+ * (`tableAt`). */
2561
+ getTableAutoFilter(table: number): AutoFilterResult;
2562
+ setTableAutoFilter(table: number, filter: AutoFilter): Status;
2563
+ removeTableAutoFilter(table: number): Status;
2564
+ applyTableAutoFilter(table: number): Status;
2565
+ clearTableAutoFilter(table: number): Status;
2566
+ evaluateTableAutoFilter(table: number): AutoFilterEvalResult;
2567
+
2568
+ /** Checks `value` against the validation rule covering `(row, col)` without
2569
+ * storing it. The first rule in `getValidations` order wins on overlap. */
2570
+ validateValue(sheet: number, row: number, col: number, value: Value): ValidationOutcomeResult;
2571
+ /** Enumerates populated cells whose value fails their validation rule, in
2572
+ * row-major order, one page at a time; paging as `getCellsInRange`. */
2573
+ listInvalidCells(sheet: number, cursor?: number | null, limit?: number | null): CellsInRangeResult;
2574
+
2575
+ /** Lists the sheet's threaded comments, replies included. */
2576
+ getThreadedComments(sheet: number): ThreadedCommentsResult;
2577
+ /** Adds a threaded comment. An empty `parentId` opens a new thread at
2578
+ * `row` / `col`; otherwise it replies to that thread. */
2579
+ addThreadedComment(sheet: number, comment: Partial<ThreadedComment> & Pick<ThreadedComment, 'id' | 'text'>): Status;
2580
+ /** Replaces the text and mentions of the comment with `id`. */
2581
+ editThreadedComment(sheet: number, id: string, text: string, mentions: Mention[]): Status;
2582
+ /** Sets the resolved state of the thread opened by `threadId`. */
2583
+ setThreadResolved(sheet: number, threadId: string, done: boolean): Status;
2584
+ /** Removes a comment; removing an opening comment removes its thread. */
2585
+ removeThreadedComment(sheet: number, id: string): Status;
2586
+ /** Lists the workbook's persons. */
2587
+ getPersons(): PersonsResult;
2588
+ addPerson(person: Person): Status;
2589
+ /** Fails while a threaded comment or mention still names the person. */
2590
+ removePerson(id: string): Status;
2591
+
2592
+ /** Sniffs the format and pixel size of PNG, JPEG, GIF or BMP bytes without touching the workbook. */
2593
+ probeImage(bytes: Uint8Array): ImageInfoResult;
2594
+ /** Lists the anchored objects of the sheet's drawing, in document order. */
2595
+ listDrawingObjects(sheet: number): ListResult<DrawingObject>;
2596
+ /** Returns a copy of the media bytes of the picture `objectId`. */
2597
+ getImage(sheet: number, objectId: number): ImageResult;
2598
+ /** Inserts `bytes` as a picture; existing drawing content is kept. */
2599
+ insertImage(sheet: number, bytes: Uint8Array, opts?: ImageInsertOptions): InsertImageResult;
2600
+ /** Removes the picture `objectId` and its media once nothing else references it. */
2601
+ removeImage(sheet: number, objectId: number): Status;
2602
+
2603
+ passthroughCount(): NumberResult;
1853
2604
  passthroughAt(idx: number): PassthroughEntry;
1854
2605
 
1855
2606
  /** Returns the number of PivotTables anchored on `sheet`. */
1856
- pivotCount(sheet: number): number;
2607
+ pivotCount(sheet: number): NumberResult;
1857
2608
  /** Evaluates and projects a PivotTable into concrete grid cells. */
1858
2609
  pivotLayout(sheet: number, pivotIndex: number): PivotLayoutResult;
1859
2610
 
1860
2611
  // ---- PivotCache mutation -----------------------------------------------
1861
2612
  /** Returns the number of pivot caches owned by the workbook. */
1862
- pivotCacheCount(): number;
2613
+ pivotCacheCount(): NumberResult;
1863
2614
  /** Returns `{ status, index: cacheId }` for the cache at flat
1864
2615
  * index `idx`. */
1865
2616
  pivotCacheIdAt(idx: number): AddStyleResult;
@@ -1875,7 +2626,7 @@ export interface Workbook {
1875
2626
  pivotCacheSetWorksheetSource(cacheId: number, source: PivotWorksheetSource): Status;
1876
2627
 
1877
2628
  /** Number of fields on the cache identified by `cacheId`. */
1878
- pivotCacheFieldCount(cacheId: number): number;
2629
+ pivotCacheFieldCount(cacheId: number): NumberResult;
1879
2630
  /** Reads the name of the cache field at `fieldIdx`. */
1880
2631
  pivotCacheFieldName(cacheId: number, fieldIdx: number): StringResult;
1881
2632
  /** Appends a new field with the given UTF-8 name to the cache.
@@ -1885,7 +2636,7 @@ export interface Workbook {
1885
2636
  pivotCacheFieldClear(cacheId: number): Status;
1886
2637
 
1887
2638
  /** Number of shared items configured on cache field `fieldIdx`. */
1888
- pivotCacheFieldSharedItemCount(cacheId: number, fieldIdx: number): number;
2639
+ pivotCacheFieldSharedItemCount(cacheId: number, fieldIdx: number): NumberResult;
1889
2640
  /** Appends a numeric shared item to cache field `fieldIdx`. */
1890
2641
  pivotCacheFieldAddSharedItemNumber(cacheId: number, fieldIdx: number, value: number): Status;
1891
2642
  /** Appends a text shared item to cache field `fieldIdx`. */
@@ -1900,7 +2651,7 @@ export interface Workbook {
1900
2651
  pivotCacheFieldClearSharedItems(cacheId: number, fieldIdx: number): Status;
1901
2652
 
1902
2653
  /** Returns the number of records on the cache. */
1903
- pivotCacheRecordCount(cacheId: number): number;
2654
+ pivotCacheRecordCount(cacheId: number): NumberResult;
1904
2655
  /** Appends a new empty record. `index` carries the new record's index. */
1905
2656
  pivotCacheRecordAdd(cacheId: number): AddStyleResult;
1906
2657
  /** Drops every record from the cache. */
@@ -1940,7 +2691,7 @@ export interface Workbook {
1940
2691
  pivotSetLayout(sheet: number, pivotIdx: number, layout: PivotReportLayout): Status;
1941
2692
 
1942
2693
  /** Number of fields configured on the pivot. */
1943
- pivotFieldCount(sheet: number, pivotIdx: number): number;
2694
+ pivotFieldCount(sheet: number, pivotIdx: number): NumberResult;
1944
2695
  /** Appends a new field. Returns `{ status, index: fieldIdx }`. */
1945
2696
  pivotFieldAdd(sheet: number, pivotIdx: number, spec: PivotFieldSpec): AddStyleResult;
1946
2697
  /** Drops every field from the pivot. */
@@ -1952,10 +2703,6 @@ export interface Workbook {
1952
2703
  pivotFieldSetSort(sheet: number, pivotIdx: number, fieldIdx: number, ascending: boolean, byField: string): Status;
1953
2704
  /** Sets the `subtotal_top` flag on pivot field `fieldIdx`. */
1954
2705
  pivotFieldSetSubtotalTop(sheet: number, pivotIdx: number, fieldIdx: number, top: boolean): Status;
1955
- /** Appends an aggregation to pivot field `fieldIdx`. */
1956
- pivotFieldAddAggregation(sheet: number, pivotIdx: number, fieldIdx: number, agg: PivotAggregation): Status;
1957
- /** Drops every aggregation from pivot field `fieldIdx`. */
1958
- pivotFieldClearAggregations(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1959
2706
  /** Appends a manual-filter item to pivot field `fieldIdx`, addressed by
1960
2707
  * its label. The item carries no cache binding, so the filter engine
1961
2708
  * matches source records by comparing their rendered label against
@@ -1985,7 +2732,15 @@ export interface Workbook {
1985
2732
  /** Drops every subtotal-fn entry from pivot field `fieldIdx`. */
1986
2733
  pivotFieldClearSubtotalFns(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1987
2734
  /** Configures date-grouping on pivot field `fieldIdx`. Pass `-1` for
1988
- * `startYear` / `endYear` to leave the bound unset. */
2735
+ * `startYear` / `endYear` to leave the Year-truncation bound unset
2736
+ * (meaningful only for `PivotDateGrouping.Year`). `intervalDays` is
2737
+ * the `PivotDateGrouping.Days`-only bucket width in whole days; pass
2738
+ * `1` for every other granularity. `startSerial` / `endSerial` are
2739
+ * the `Days`-only Start/End window as Excel date serials -- pass
2740
+ * `-1` for either to leave it auto (Start = the field's data
2741
+ * minimum, End = the data maximum plus one day); ignored otherwise.
2742
+ * With `Days`, a zero `intervalDays` or a start after the end is
2743
+ * rejected with `kInvalidArgument`. */
1989
2744
  pivotFieldSetDateGroup(
1990
2745
  sheet: number,
1991
2746
  pivotIdx: number,
@@ -1994,11 +2749,15 @@ export interface Workbook {
1994
2749
  calendar: PivotCalendar,
1995
2750
  startYear: number,
1996
2751
  endYear: number,
2752
+ intervalDays: number,
2753
+ startSerial: number,
2754
+ endSerial: number,
1997
2755
  ): Status;
1998
2756
  /** Removes the date-grouping config from pivot field `fieldIdx`. */
1999
2757
  pivotFieldClearDateGroup(sheet: number, pivotIdx: number, fieldIdx: number): Status;
2000
- /** Sets the OOXML number-format string on pivot field `fieldIdx`.
2001
- * Pass an empty string to clear. */
2758
+ /** Sets the `numFmtId` of pivot field `fieldIdx`, as a decimal string
2759
+ * naming a built-in id or one returned by `addNumFmt`. Pass an empty
2760
+ * string to clear; any other unknown id is rejected. */
2002
2761
  pivotFieldSetNumberFormat(sheet: number, pivotIdx: number, fieldIdx: number, utf8: string): Status;
2003
2762
 
2004
2763
  /** Replaces the row-axis field order with `indices`. Each entry must
@@ -2008,7 +2767,7 @@ export interface Workbook {
2008
2767
  pivotSetColFieldOrder(sheet: number, pivotIdx: number, indices: ReadonlyArray<number>): Status;
2009
2768
 
2010
2769
  /** Number of `<dataField>` entries on the pivot. */
2011
- pivotDataFieldCount(sheet: number, pivotIdx: number): number;
2770
+ pivotDataFieldCount(sheet: number, pivotIdx: number): NumberResult;
2012
2771
  /** Appends a new data-field entry. */
2013
2772
  pivotDataFieldAdd(sheet: number, pivotIdx: number, spec: PivotDataFieldSpec): AddStyleResult;
2014
2773
  /** Drops every data-field entry from the pivot. */
@@ -2018,7 +2777,7 @@ export interface Workbook {
2018
2777
 
2019
2778
  /** Number of active (slicer-applied) filters on the pivot. Counts only
2020
2779
  * the entries this session added -- see {@link PivotFilterResult}. */
2021
- pivotFilterCount(sheet: number, pivotIdx: number): number;
2780
+ pivotFilterCount(sheet: number, pivotIdx: number): NumberResult;
2022
2781
  /** Appends an active filter. The entry is session state and is not
2023
2782
  * written by `save`; see {@link PivotFilterResult}. */
2024
2783
  pivotFilterAdd(sheet: number, pivotIdx: number, spec: PivotFilterSpec): Status;
@@ -2177,6 +2936,27 @@ export interface Workbook {
2177
2936
  setRowHidden(sheet: number, row: number, hidden: boolean): Status;
2178
2937
  /** Sets / replaces the row outline level at `row` (clamped to 0..255). */
2179
2938
  setRowOutline(sheet: number, row: number, level: number): Status;
2939
+ /** Removes the height override at `row`, returning it to the sheet default. */
2940
+ clearRowHeight(sheet: number, row: number): Status;
2941
+
2942
+ /** Reads the sheet's default column / row metrics. */
2943
+ getSheetFormatDefaults(sheet: number): SheetFormatDefaultsResult;
2944
+ /** Replaces the sheet's default column / row metrics. A `has*` flag left out defaults to whether its value was supplied. */
2945
+ setSheetFormatDefaults(sheet: number, defaults: Partial<SheetFormatDefaults>): Status;
2946
+
2947
+ /** Rectangle covering the inclusive cell range, in points from the top-left of A1.
2948
+ * Hidden rows and columns contribute zero extent. */
2949
+ getCellRectPt(sheet: number, range: MergeRange, mode: GeometryMode): CellRectResult;
2950
+ /** Effective column width in points; zero when hidden. */
2951
+ getColumnWidthPt(sheet: number, col: number, mode: GeometryMode): NumberResult;
2952
+ /** Effective row height in points; zero when hidden. */
2953
+ getRowHeightPt(sheet: number, row: number): NumberResult;
2954
+ /** The character-unit to point conversion model for the workbook's Normal font. */
2955
+ getWidthModel(sheet: number, mode: GeometryMode): WidthModelResult;
2956
+ /** Converts a column width in characters to points. */
2957
+ columnCharsToPt(sheet: number, mode: GeometryMode, chars: number): NumberResult;
2958
+ /** Inverse of `columnCharsToPt`; a width at or below the padding maps to zero characters. */
2959
+ columnPtToChars(sheet: number, mode: GeometryMode, pt: number): NumberResult;
2180
2960
 
2181
2961
  /** Returns `{ status, xfIndex }` for the cell at `(sheet, row, col)`. */
2182
2962
  getCellXfIndex(sheet: number, row: number, col: number): CellXfIndexResult;
@@ -2239,24 +3019,24 @@ export interface Workbook {
2239
3019
  addDxf(record: DxfRecord): AddStyleResult;
2240
3020
 
2241
3021
  /** Returns the number of font records currently registered. */
2242
- fontCount(): number;
3022
+ fontCount(): NumberResult;
2243
3023
  /** Returns the number of fill records currently registered. */
2244
- fillCount(): number;
3024
+ fillCount(): NumberResult;
2245
3025
  /** Returns the number of border records currently registered. */
2246
- borderCount(): number;
3026
+ borderCount(): NumberResult;
2247
3027
  /** Returns the number of `<xf>` records currently registered. */
2248
- xfCount(): number;
3028
+ xfCount(): NumberResult;
2249
3029
  /** Returns the number of `<dxf>` records available for CF `dxfId`. */
2250
- dxfCount(): number;
3030
+ dxfCount(): NumberResult;
2251
3031
 
2252
3032
  /** Returns the number of named cell styles (`<cellStyle>` entries)
2253
3033
  * registered. Zero for workbooks that do not declare any named
2254
3034
  * styles. */
2255
- cellStyleCount(): number;
3035
+ cellStyleCount(): NumberResult;
2256
3036
  /** Returns the number of `<cellStyleXfs>` records — the named-style
2257
3037
  * xf table referenced by `CellStyleResult.xfId`. Independent of the
2258
3038
  * per-cell `cellXfs` table. */
2259
- cellStyleXfCount(): number;
3039
+ cellStyleXfCount(): NumberResult;
2260
3040
  /** Returns the named cell style at `index`. Out-of-range indices
2261
3041
  * surface `kInvalidArgument` via `status`. */
2262
3042
  getCellStyle(index: number): CellStyleResult;
@@ -2267,10 +3047,30 @@ export interface Workbook {
2267
3047
  * `<cellStyleXfs>` index, which is what `setCellStyle` and
2268
3048
  * `CellXf.xfId` reference. */
2269
3049
  addCellStyleXf(record: CellXf): AddStyleResult;
2270
- /** Adds or replaces the `<cellStyle>` entry named `name`. `builtinId` is
2271
- * an OOXML ordinal `0..47`, or `0xFFFFFFFF` for a custom style; it is
2272
- * required because the binding takes a fixed argument count. */
2273
- setCellStyle(name: string, xfId: number, builtinId: number): Status;
3050
+ /** Adds or replaces the `<cellStyle>` entry named `record.name`. Absent
3051
+ * fields default to `xfId` 0, a custom style (`0xFFFFFFFF`), level 0 and
3052
+ * both flags false. */
3053
+ setCellStyle(record: CellStyleRecord): Status;
3054
+ /** Removes the `<cellStyle>` named `name`; cell formats that used it are
3055
+ * repointed at the Normal style. */
3056
+ removeCellStyle(name: string): Status;
3057
+
3058
+ /** The 12 theme colours (`clrScheme` order) and the theme typefaces. The
3059
+ * default theme is reported when the part is absent or unparseable;
3060
+ * `source` tells the cases apart. */
3061
+ getTheme(): ThemeResult;
3062
+ /** Rewrites the 12 scheme colours (`clrScheme` order, alpha ignored). A
3063
+ * workbook without a theme part first gets a minimal one. */
3064
+ setThemeColors(colors: number[]): Status;
3065
+ /** Rewrites the theme's major and minor typefaces. */
3066
+ setThemeFonts(fonts: ThemeFonts): Status;
3067
+ /** Resolves a colour specification to ARGB against the theme and the
3068
+ * indexed palette; `context` decides what an automatic colour means. */
3069
+ resolveColor(spec: ColorSpec, context: ColorContext): ResolvedColorResult;
3070
+ /** The formatting a cell shows: the xf chosen from cell, row, column or
3071
+ * the default, with its colours resolved. Conditional formatting is not
3072
+ * applied. */
3073
+ getEffectiveStyle(sheet: number, row: number, col: number): EffectiveStyleResult;
2274
3074
 
2275
3075
  /** Returns every external-link record carried by the workbook in
2276
3076
  * `<externalReferences>` document order. Empty for fresh workbooks
@@ -2288,6 +3088,8 @@ export interface Workbook {
2288
3088
  clearMerges(sheet: number): Status;
2289
3089
  /** Returns every merge range on `sheet` as a JS array. */
2290
3090
  getMerges(sheet: number): ListResult<MergeRange>;
3091
+ /** Returns the merge ranges on `sheet` that intersect `range`, in storage order. */
3092
+ getMergesInRange(sheet: number, range: MergeRange): ListResult<MergeRange>;
2291
3093
 
2292
3094
  /** Returns the cell comment at `(sheet, row, col)`, or `null` when absent. */
2293
3095
  getComment(sheet: number, row: number, col: number): CommentEntry | null;
@@ -2365,11 +3167,12 @@ export interface Workbook {
2365
3167
  /** Returns the cells that `(sheet, row, col)` directly reads
2366
3168
  * (1-step precedents) when `depth <= 1`, or every cell reached
2367
3169
  * within `depth` BFS steps otherwise. `depth` is capped at 32 to
2368
- * avoid runaway expansion in cyclic graphs. */
2369
- precedents(sheet: number, row: number, col: number, depth: number): ReadonlyArray<CellNode>;
3170
+ * avoid runaway expansion in cyclic graphs. An invalid sheet, row or
3171
+ * column yields an empty list with `status.ok === false`. */
3172
+ precedents(sheet: number, row: number, col: number, depth: number): ListResult<CellNode>;
2370
3173
  /** Returns the cells that read `(sheet, row, col)` directly
2371
3174
  * (1-step dependents). Same depth semantics as `precedents`. */
2372
- dependents(sheet: number, row: number, col: number, depth: number): ReadonlyArray<CellNode>;
3175
+ dependents(sheet: number, row: number, col: number, depth: number): ListResult<CellNode>;
2373
3176
 
2374
3177
  /** Returns metadata for the function `name` (case-insensitive). When
2375
3178
  * the function is unknown, returns `{ok: false}`. `locale` selects
@@ -2379,20 +3182,21 @@ export interface Workbook {
2379
3182
  functionMetadata(name: string, locale: number): FunctionMetadataResult;
2380
3183
  /** Returns every registered function's canonical name in ascending
2381
3184
  * sort order. */
2382
- functionNames(): ReadonlyArray<string>;
3185
+ functionNames(): ListResult<string>;
2383
3186
 
2384
3187
  /** Returns the localized display name for the canonical function
2385
3188
  * `canonicalName` in `locale`. No alias table exists in any locale,
2386
3189
  * so this always returns the canonical name unchanged; localized
2387
- * display names belong to the host's provider document. Returns the
2388
- * empty string when the canonical name does not match a registered
2389
- * function. */
2390
- localizeFunctionName(canonicalName: string, locale: number): string;
3190
+ * display names belong to the host's provider document. `value` is
3191
+ * the empty string, with `status.ok === false`, when the canonical
3192
+ * name does not match a registered function. */
3193
+ localizeFunctionName(canonicalName: string, locale: number): StringResult;
2391
3194
  /** Inverse of `localizeFunctionName`: returns the canonical English
2392
3195
  * name for the localized function `localizedName`. With no alias
2393
3196
  * table this is a case-insensitive canonical-name match, in every
2394
- * locale. Returns the empty string when no function matches. */
2395
- canonicalizeFunctionName(localizedName: string, locale: number): string;
3197
+ * locale. `value` is the empty string, with `status.ok === false`,
3198
+ * when no function matches. */
3199
+ canonicalizeFunctionName(localizedName: string, locale: number): StringResult;
2396
3200
 
2397
3201
  /** Returns dynamic-array spill info for `(sheet, row, col)`.
2398
3202
  * When the cell is part of a spill region (anchor or phantom),
@@ -2409,9 +3213,10 @@ export interface WorkbookCtor {
2409
3213
  createDefault(): Workbook;
2410
3214
  /** Workbook with no sheets. */
2411
3215
  createEmpty(): Workbook;
2412
- /** Loads from an in-memory `.xlsx` byte buffer. The returned wrapper
2413
- * may be invalid (`!isValid()`) on failure; consult
2414
- * `lastErrorMessage()` for diagnostics. */
3216
+ /** Loads from an in-memory workbook byte buffer, auto-detecting
3217
+ * `.xlsx` vs `.xlsb` from the package contents (there is no filename
3218
+ * to route on). The returned wrapper may be invalid (`!isValid()`) on
3219
+ * failure; consult `lastErrorMessage()` for diagnostics. */
2415
3220
  loadBytes(bytes: Uint8Array): Workbook;
2416
3221
  }
2417
3222