@libraz/formulon 0.9.7 → 0.11.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.
@@ -27,12 +27,37 @@ export interface Status {
27
27
  ok: boolean;
28
28
  /** Numeric `fm_status_t`. 0 on success. */
29
29
  status: number;
30
- /** Thread-local last-error message (empty on success). */
30
+ /** Describes the failure this call hit; empty on success. Normally the
31
+ * thread-local last-error message the C ABI recorded, but a rejection
32
+ * the binding raised itself -- a destroyed handle, a missing or
33
+ * wrongly-shaped argument -- carries its own message instead, never the
34
+ * residue of an earlier call. */
31
35
  message: string;
32
- /** Optional thread-local context string (empty on success). */
36
+ /** Optional thread-local context string. Empty on success, and empty for
37
+ * a failure the binding raised before reaching the C ABI. */
33
38
  context: string;
34
39
  }
35
40
 
41
+ /** Per-call telemetry returned by `Workbook.recalcParallel`. The five
42
+ * scheduler counters are `uint64_t` in the C ABI but are exposed as
43
+ * JavaScript `number` values by the WASM binding. They are exact through
44
+ * `Number.MAX_SAFE_INTEGER` (2^53 - 1). */
45
+ export interface ParallelRecalcStats {
46
+ cellsEvaluated: number;
47
+ sccsProcessed: number;
48
+ parallelSteps: number;
49
+ serialFallbackSteps: number;
50
+ cycleRecoveries: number;
51
+ workerThreadsStarted: number;
52
+ workerThreadsUsed: number;
53
+ }
54
+
55
+ /** `{ status, stats }` returned by `Workbook.recalcParallel`. */
56
+ export interface ParallelRecalcResult {
57
+ status: Status;
58
+ stats: ParallelRecalcStats;
59
+ }
60
+
36
61
  /** A JS array with the status of the list enumeration that produced it. */
37
62
  export type ListResult<T> = ReadonlyArray<T> & { readonly status: Status };
38
63
 
@@ -75,14 +100,65 @@ export interface EvalArrayResult {
75
100
  cells: Value[][];
76
101
  }
77
102
 
78
- /** Return type of `Workbook.save()` / `Workbook.saveEx(format)`. */
103
+ /** Return type of `Workbook.save()` / `Workbook.saveAs(format)`. */
79
104
  export interface SaveResult {
80
105
  status: Status;
81
106
  /** Freshly-allocated `Uint8Array` on success; `null` on failure. */
82
107
  bytes: Uint8Array | null;
83
108
  }
84
109
 
85
- /** `fm_workbook_format_t` ordinals: container format for `saveEx`. */
110
+ /**
111
+ * Return type of `Workbook.saveWithDiagnostics(format)`.
112
+ *
113
+ * A field means the same thing whichever container was written; where the
114
+ * underlying event exists in only one container, the other simply never
115
+ * raises it. Coverage is partial by design — an all-zero result means
116
+ * none of the losses below occurred, not that nothing was logged.
117
+ *
118
+ * Summing these does NOT give "how many things did I lose":
119
+ * `droppedPartCount` and `droppedRelationshipCount` both rise for one
120
+ * dropped part.
121
+ */
122
+ export interface SaveDiagnosticsResult extends SaveResult {
123
+ /** Formula cells emitted as cached literals. Always zero for XLSX. */
124
+ downgradedFormulaCount: number;
125
+ /** Sheet features not lowered to records. Always zero for XLSX. */
126
+ deferredFeatureCount: number;
127
+ /** Passthrough parts dropped for colliding with a generated path, or
128
+ * for two entries claiming one path. Both containers. */
129
+ droppedPartCount: number;
130
+ /** Relationships dropped because their target part is gone. Both
131
+ * containers, at package / workbook / (XLSB) sheet scope. Rises with
132
+ * `droppedPartCount` for one dropped part — do not add them. */
133
+ droppedRelationshipCount: number;
134
+ /** Tables emitted under a writer-assigned id. Always zero for XLSB. */
135
+ renumberedPartCount: number;
136
+ }
137
+
138
+ /**
139
+ * Return type of `Workbook.readDiagnostics()`. Same contract as
140
+ * `SaveDiagnosticsResult`: one meaning per field across both containers,
141
+ * partial coverage by design.
142
+ */
143
+ export interface ReadDiagnosticsResult {
144
+ status: Status;
145
+ /** Formula cells whose stored formula could not be decoded. XLSB only. */
146
+ undecodedFormulaCount: number;
147
+ /** Defined names skipped for the same reason. XLSB only. */
148
+ undecodedDefinedNameCount: number;
149
+ /** Package parts whose content type could not be resolved, so they were
150
+ * not decoded. XLSB only — the XLSX reader keeps unmodelled parts as
151
+ * passthrough instead of dropping them. */
152
+ undecodedPartCount: number;
153
+ /** Presentation-overlay entries dropped for an unusable reference: one
154
+ * per merge / hyperlink / data validation, one per conditional-format
155
+ * block (a block can carry several rules). XLSX only. */
156
+ skippedFeatureCount: number;
157
+ /** Workbook parts whose content type was unrecognised. Max 1. XLSX only. */
158
+ unknownContentTypeCount: number;
159
+ }
160
+
161
+ /** `fm_workbook_format_t` ordinals: container format for `saveAs`. */
86
162
  export enum WorkbookFormat {
87
163
  Unknown = 0,
88
164
  Xlsx = 1,
@@ -123,6 +199,32 @@ export interface TableEntry {
123
199
  sheetIndex?: number;
124
200
  }
125
201
 
202
+ /** Authoring input for a worksheet table. `columns` must have exactly one
203
+ * name per column in `ref`; `styleName` follows Excel's built-in TableStyle
204
+ * names. With `headerRow` (the default), the caller still writes the header
205
+ * cells: Excel expects the first row of `ref` to hold the column names. */
206
+ export interface TableInput {
207
+ sheetIndex: number;
208
+ ref: string;
209
+ name: string;
210
+ displayName?: string;
211
+ columns: string[];
212
+ styleName?: string;
213
+ headerRow?: boolean;
214
+ totalsRow?: boolean;
215
+ }
216
+
217
+ /** Partial table metadata update. Omitted fields preserve their existing
218
+ * values; an empty `styleName` explicitly removes the table style. When
219
+ * omitted, `ref` also preserves the current range. `headerRow` and
220
+ * `totalsRow` update their flags only when supplied. */
221
+ export interface TableUpdateInput {
222
+ ref?: string;
223
+ styleName?: string;
224
+ headerRow?: boolean;
225
+ totalsRow?: boolean;
226
+ }
227
+
126
228
  /** Return type of `Workbook.passthroughAt(idx)`. */
127
229
  export interface PassthroughEntry {
128
230
  status: Status;
@@ -320,6 +422,8 @@ export interface PivotFilterSpec {
320
422
  axis: PivotAxis;
321
423
  fieldName: string;
322
424
  type: PivotFilterType;
425
+ /** Data-field aggregate scored by value filters. Defaults to 0. */
426
+ dataFieldIndex?: number;
323
427
  valueKind?: PivotFilterValueKind;
324
428
  valueInt?: number;
325
429
  valueDouble?: number;
@@ -329,6 +433,30 @@ export interface PivotFilterSpec {
329
433
  valueHighDouble?: number;
330
434
  }
331
435
 
436
+ /** Return type of `Workbook.pivotFilterAt(...)`: the stored filter plus a
437
+ * status envelope. Field names and semantics match `PivotFilterSpec`.
438
+ *
439
+ * The active-filter list is **session state**. An entry added through
440
+ * `pivotFilterAdd` affects evaluation only while the workbook handle
441
+ * lives and is not written by `save`. Conversely a `<filters>` block
442
+ * Excel wrote is preserved verbatim on save but does not appear here, so
443
+ * `pivotFilterCount` reports only what this session added. The filter
444
+ * surface that does persist is pivot field item visibility. */
445
+ export interface PivotFilterResult {
446
+ status: Status;
447
+ axis: number;
448
+ fieldName: string;
449
+ type: number;
450
+ dataFieldIndex: number;
451
+ valueKind: number;
452
+ valueInt: number;
453
+ valueDouble: number;
454
+ valueText: string;
455
+ valueHighKind: number;
456
+ valueHighInt: number;
457
+ valueHighDouble: number;
458
+ }
459
+
332
460
  /** Conditional-format match kind. Mirrors `formulon::cf::CFMatchKind`. */
333
461
  export enum CfMatchKind {
334
462
  DifferentialFormat = 0,
@@ -337,6 +465,28 @@ export enum CfMatchKind {
337
465
  IconSet = 3,
338
466
  }
339
467
 
468
+ /** Excel cell-error ordinals. Mirrors `formulon::ErrorCode`; these are the
469
+ * values carried by `Value.errorCode` and accepted by `setError`. */
470
+ export enum ErrorCode {
471
+ Null = 0,
472
+ Div0 = 1,
473
+ Value = 2,
474
+ Ref = 3,
475
+ Name = 4,
476
+ Num = 5,
477
+ NA = 6,
478
+ GettingData = 7,
479
+ Spill = 8,
480
+ Calc = 9,
481
+ Field = 10,
482
+ Blocked = 11,
483
+ Connect = 12,
484
+ External = 13,
485
+ Busy = 14,
486
+ Python = 15,
487
+ Unknown = 16,
488
+ }
489
+
340
490
  /**
341
491
  * Workbook-level calc mode (`<calcPr calcMode>`).
342
492
  *
@@ -355,6 +505,20 @@ export enum CalcMode {
355
505
 
356
506
  export type ExcelProfileId = 'mac-365-ja_JP' | 'win-365-ja_JP';
357
507
 
508
+ /**
509
+ * A wall-clock reading in local civil fields, as read back from
510
+ * {@link Workbook.pinnedNow}. `month` is 1-12 and `day` is 1-31; the other
511
+ * fields follow the usual 24-hour ranges.
512
+ */
513
+ export interface CivilTime {
514
+ year: number;
515
+ month: number;
516
+ day: number;
517
+ hour: number;
518
+ minute: number;
519
+ second: number;
520
+ }
521
+
358
522
  /** RGBA colour. Channels are 0-255 (sRGB). */
359
523
  export interface CfColor {
360
524
  r: number;
@@ -412,14 +576,29 @@ export interface CfRangeResult {
412
576
  /** Resolved print geometry for one worksheet. All coordinates are 0-based. */
413
577
  export interface PaginationResult {
414
578
  status: Status;
579
+ /** The sheet's declared `_xlnm.Print_Area`. Empty when the sheet declares
580
+ * none -- it is not backfilled with the used range. Pagination itself
581
+ * still falls back to the used range in that case, so `pageCount` can be
582
+ * non-zero while this is empty. */
415
583
  printArea: Array<{ firstRow: number; firstCol: number; lastRow: number; lastCol: number }>;
416
584
  horizontalBreaks: number[];
417
585
  verticalBreaks: number[];
418
586
  pageCount: number;
419
587
  }
420
588
 
589
+ /** Sheet tab visibility, mirroring OOXML `<sheet state>`.
590
+ *
591
+ * `VeryHidden` differs from `Hidden` in that Excel leaves such a sheet
592
+ * out of its "Unhide" dialog, which is how a workbook keeps a settings
593
+ * or lookup sheet out of a user's reach. */
594
+ export enum SheetVisibility {
595
+ Visible = 0,
596
+ Hidden = 1,
597
+ VeryHidden = 2,
598
+ }
599
+
421
600
  /** Per-sheet view: zoom (10..400, default 100), frozen-pane row/col
422
- * counts, tab-hidden flag, and the display / orientation flags mirrored
601
+ * counts, tab visibility, and the display / orientation flags mirrored
423
602
  * from OOXML `<sheetView>` (gridlines, row/col headers, zero display,
424
603
  * right-to-left, tab-selected, view mode). Booleans are encoded as
425
604
  * `0`/`1` to match the embind binding's wire shape. */
@@ -427,8 +606,14 @@ export interface SheetView {
427
606
  zoomScale: number;
428
607
  freezeRows: number;
429
608
  freezeCols: number;
430
- /** Boolean stored as 0/1 to match the embind binding's wire shape. */
609
+ /** Boolean stored as 0/1 to match the embind binding's wire shape.
610
+ * The two-state view of `visibility`: `1` for both hidden states, so
611
+ * reading only this field sees a very-hidden sheet as hidden rather
612
+ * than visible. Read `visibility` to tell the two apart. */
431
613
  tabHidden: number;
614
+ /** The authoritative tab state, as a `SheetVisibility` code. Always
615
+ * agrees with `tabHidden`. */
616
+ visibility: number;
432
617
  /** `showGridLines`; default 1. */
433
618
  showGridLines: number;
434
619
  /** `showRowColHeaders`; default 1. */
@@ -501,6 +686,11 @@ export interface ColumnLayout {
501
686
  /** Boolean stored as 0/1. */
502
687
  hidden: number;
503
688
  outlineLevel: number;
689
+ /** Whether the width is logically explicit (raw presence or non-zero legacy width). */
690
+ hasWidth: number;
691
+ /** Whether the source / model carries an explicit style attribute. */
692
+ hasStyle: number;
693
+ styleXf: number;
504
694
  }
505
695
 
506
696
  /** Return type of `Workbook.getSheetColumns(sheet)`. */
@@ -516,6 +706,9 @@ export interface RowLayout {
516
706
  /** Boolean stored as 0/1. */
517
707
  hidden: number;
518
708
  outlineLevel: number;
709
+ /** Whether OOXML customFormat=1 makes the row style effective. */
710
+ hasStyle: number;
711
+ styleXf: number;
519
712
  }
520
713
 
521
714
  /** Return type of `Workbook.getSheetRowOverrides(sheet)`. */
@@ -536,6 +729,9 @@ export interface MergeRange {
536
729
  export interface HyperlinkEntry {
537
730
  row: number;
538
731
  col: number;
732
+ /** Inclusive bottom-right endpoint of the hyperlink rectangle. */
733
+ lastRow: number;
734
+ lastCol: number;
539
735
  /** Absolute or relative target (URL, email, internal ref, …). */
540
736
  target: string;
541
737
  /** In-workbook destination (empty for an external target). */
@@ -646,8 +842,9 @@ export interface CellNode {
646
842
  * `ok` is `false` when no function matches `name`; the remaining
647
843
  * fields are absent. When `ok` is `true`, `name` / `minArity` /
648
844
  * `maxArity` are always populated; `signatureTemplate` and
649
- * `description` are populated only when the locale metadata table
650
- * has an entry for this function and locale. */
845
+ * `description` are always `undefined` — the engine ships no
846
+ * human-readable function text and a host merges its own provider
847
+ * document over this result (`docs/function-metadata-schema.md`). */
651
848
  export interface FunctionMetadataResult {
652
849
  readonly ok: boolean;
653
850
  readonly name?: string;
@@ -695,9 +892,8 @@ export interface MergedFunctionMetadataResult extends FunctionMetadataResult {
695
892
  readonly localizedName?: string;
696
893
  }
697
894
 
698
- /** Signature of the pure `mergeFunctionMetadata` helper that merges a
699
- * host-supplied {@link FunctionMetadataEntry} over the engine's structural
700
- * `functionMetadata()` result.
895
+ /** Merges a host-supplied {@link FunctionMetadataEntry} over the engine's
896
+ * structural `functionMetadata()` result.
701
897
  *
702
898
  * Field precedence (first non-nullish wins):
703
899
  * - `signatureTemplate`: `entry.localized[locale].signature` ->
@@ -706,19 +902,22 @@ export interface MergedFunctionMetadataResult extends FunctionMetadataResult {
706
902
  * `entry.description` -> `base.description`
707
903
  * - `localizedName`: `entry.aliases[locale]` -> `base.name`
708
904
  *
709
- * When `entry` is `undefined`, `base` is returned verbatim. `locale` is a
710
- * BCP-47 display tag matching the keys in `aliases` / `localized`.
905
+ * When `entry` is `undefined`, `base` is returned verbatim (signature /
906
+ * description stay `undefined`). `locale` is a BCP-47 display tag matching
907
+ * the keys in `aliases` / `localized`, independent of the numeric locale
908
+ * passed to `functionMetadata()`. See `docs/function-metadata-schema.md`.
711
909
  *
712
- * NOTE: this is a **type only**. The WASM module's runtime JS is generated
713
- * and does not export a `mergeFunctionMetadata` function. The helper is a
714
- * pure function whose canonical implementation ships in
715
- * `@libraz/formulon-native`; a host should import it from there or
716
- * reimplement it per `docs/function-metadata-schema.md`. */
717
- export type MergeFunctionMetadata = (
910
+ * A pure host-side helper: it touches no WASM state and is exported from
911
+ * this package's hand-written entry point rather than the generated module
912
+ * glue. `@libraz/formulon-native` exports the same function. */
913
+ export function mergeFunctionMetadata(
718
914
  base: FunctionMetadataResult,
719
915
  entry: FunctionMetadataEntry | undefined,
720
916
  locale: string,
721
- ) => MergedFunctionMetadataResult;
917
+ ): MergedFunctionMetadataResult;
918
+
919
+ /** Signature of {@link mergeFunctionMetadata}. */
920
+ export type MergeFunctionMetadata = typeof mergeFunctionMetadata;
722
921
 
723
922
  /** Spill region info returned by `spillInfo(sheet, row, col)`. */
724
923
  export interface SpillInfo {
@@ -746,10 +945,11 @@ export interface ConditionalFormatRange {
746
945
  * 13 containsErrors, 14 notContainsErrors, 15 timePeriod,
747
946
  * 16 duplicateValues, 17 uniqueValues.
748
947
  *
749
- * Visual rule kinds (`colorScale` / `dataBar` / `iconSet`) round-trip
750
- * through the OOXML reader / writer but their visual sub-spec fields
751
- * are not yet surfaced through this read API; only `id`, `type`,
752
- * `priority`, `stopIfTrue`, and `sqref` populate for those kinds.
948
+ * `id`, `type`, `priority`, `stopIfTrue` and `sqref` populate for every
949
+ * rule kind; the remaining fields are engaged by the kinds noted on
950
+ * each. A visual rule (`colorScale` / `dataBar` / `iconSet`) carries its
951
+ * full sub-spec, so an entry read back here can be handed straight to
952
+ * `addConditionalFormat`.
753
953
  */
754
954
  export interface ConditionalFormatEntry {
755
955
  readonly id: string;
@@ -789,6 +989,19 @@ export interface ConditionalFormatEntry {
789
989
  readonly showValue: boolean;
790
990
  readonly minLengthPct: number;
791
991
  readonly maxLengthPct: number;
992
+ /**
993
+ * `x14` extension payload. Present whenever the rule states the
994
+ * setting; a rule read back from a workbook always carries all six, so
995
+ * the object can be handed straight to `addConditionalFormat`.
996
+ *
997
+ * `axisPosition` is 0 = automatic, 1 = middle, 2 = none.
998
+ */
999
+ readonly gradient?: boolean;
1000
+ readonly axisPosition?: number;
1001
+ readonly negativeFill?: CfColor;
1002
+ readonly border?: CfColor;
1003
+ readonly negativeBorder?: CfColor;
1004
+ readonly axisColor?: CfColor;
792
1005
  };
793
1006
  /** Engaged for `iconSet` rules. */
794
1007
  readonly iconSet?: {
@@ -796,6 +1009,9 @@ export interface ConditionalFormatEntry {
796
1009
  readonly thresholds: ReadonlyArray<CfValueObjectInput>;
797
1010
  readonly reverse: boolean;
798
1011
  readonly showValue: boolean;
1012
+ /** Round-trip only: the `percent` attribute is preserved across load
1013
+ * and save but never consulted during evaluation. Each threshold
1014
+ * carries its own `type`, and that type is what interprets it. */
799
1015
  readonly percent: boolean;
800
1016
  };
801
1017
  }
@@ -836,6 +1052,18 @@ export interface ConditionalFormatInput {
836
1052
  showValue?: boolean;
837
1053
  minLengthPct?: number;
838
1054
  maxLengthPct?: number;
1055
+ /**
1056
+ * `x14` extension payload. Omit a key to keep the model default:
1057
+ * gradient fill on, automatic axis, negative fill equal to `fill`, no
1058
+ * border, and a black axis. `axisPosition` is 0 = automatic,
1059
+ * 1 = middle, 2 = none.
1060
+ */
1061
+ gradient?: boolean;
1062
+ axisPosition?: number;
1063
+ negativeFill?: CfColor;
1064
+ border?: CfColor;
1065
+ negativeBorder?: CfColor;
1066
+ axisColor?: CfColor;
839
1067
  };
840
1068
  /** Payload for type 4 (`iconSet`). `name` is `formulon::cf::IconSetName` ordinal. */
841
1069
  iconSet?: {
@@ -843,6 +1071,9 @@ export interface ConditionalFormatInput {
843
1071
  thresholds: ReadonlyArray<CfValueObjectInput>;
844
1072
  reverse?: boolean;
845
1073
  showValue?: boolean;
1074
+ /** Round-trip only: preserved across load and save but never
1075
+ * consulted during evaluation (each threshold's own `type` is
1076
+ * authoritative). */
846
1077
  percent?: boolean;
847
1078
  };
848
1079
  }
@@ -863,6 +1094,53 @@ export interface CellXfResult {
863
1094
  horizontalAlign: number;
864
1095
  verticalAlign: number;
865
1096
  wrapText: boolean;
1097
+ /** OOXML `justifyLastLine`; effective with distributed horizontal alignment. */
1098
+ justifyLastLine: boolean;
1099
+ /** Whether the source `<xf>` carried an `<alignment>` child. */
1100
+ hasAlignment: boolean;
1101
+ /** Whether `horizontal="..."` was explicitly present. */
1102
+ hasHorizontalAlign: boolean;
1103
+ /** Whether `vertical="..."` was explicitly present. */
1104
+ hasVerticalAlign: boolean;
1105
+ /** Whether `wrapText="..."` was explicitly present. */
1106
+ hasWrapText: boolean;
1107
+ /** Whether `justifyLastLine="..."` was explicitly present. */
1108
+ hasJustifyLastLine: boolean;
1109
+ /** OOXML `textRotation`; present only when the source attribute existed. */
1110
+ textRotation?: number;
1111
+ /** OOXML `indent`; present only when the source attribute existed. */
1112
+ indent?: number;
1113
+ /** OOXML signed `relativeIndent`; present only when the source attribute existed. */
1114
+ relativeIndent?: number;
1115
+ /** OOXML `shrinkToFit`; present only when the source attribute existed. */
1116
+ shrinkToFit?: boolean;
1117
+ /** OOXML `readingOrder`; present only when the source attribute existed. */
1118
+ readingOrder?: number;
1119
+ /** Index into `<cellStyleXfs>` of the named style this format inherits
1120
+ * from. Always 0 for a record read back from `getCellStyleXf`. */
1121
+ xfId?: number;
1122
+ }
1123
+
1124
+ /** How an OOXML `<color>` element expressed its value.
1125
+ * Mirrors `formulon::io::ColorSpec`.
1126
+ *
1127
+ * A record read from a workbook carries the original specification here.
1128
+ * When `kind` is non-zero, this selector is authoritative; the sibling
1129
+ * `*Argb` field is not an Excel-rendered value for theme/indexed/auto
1130
+ * selectors. It is literal RGB for `kind === 1`, or a compatibility
1131
+ * fallback otherwise. Leave `kind` at 0 on a record built from scratch and
1132
+ * the writer emits the sibling `*Argb` as `rgb`. */
1133
+ export interface ColorSpec {
1134
+ /** 0=none, 1=rgb, 2=theme, 3=indexed, 4=auto. */
1135
+ kind: number;
1136
+ /** AARRGGBB; meaningful when `kind` is 1. */
1137
+ rgb: number;
1138
+ /** Theme index; meaningful when `kind` is 2. */
1139
+ theme: number;
1140
+ /** Theme tint in -1..1; meaningful when `kind` is 2. */
1141
+ tint: number;
1142
+ /** Legacy palette index; meaningful when `kind` is 3. */
1143
+ indexed: number;
866
1144
  }
867
1145
 
868
1146
  /** Plain-data shape of a font record. Mirrors `formulon::io::FontRecord`. */
@@ -872,30 +1150,56 @@ export interface FontRecord {
872
1150
  bold: boolean;
873
1151
  italic: boolean;
874
1152
  strike: boolean;
1153
+ /** Whether the source carried a `<b>` element at all. An absent element
1154
+ * on a differential font means "leave bold unchanged"; `hasBold` with
1155
+ * `bold: false` means "switch bold off". */
1156
+ hasBold: boolean;
1157
+ /** Whether the source carried an `<i>` element at all. */
1158
+ hasItalic: boolean;
1159
+ /** Whether the source carried a `<strike>` element at all. */
1160
+ hasStrike: boolean;
875
1161
  /** 0=none, 1=single, 2=double, 3=singleAccounting, 4=doubleAccounting. */
876
1162
  underline: number;
877
1163
  /** 0=baseline, 1=superscript, 2=subscript. */
878
1164
  vertAlign: number;
879
- /** AARRGGBB packed colour. */
1165
+ /** Whether the source carried a `<family>` element. */
1166
+ hasFamily: boolean;
1167
+ /** OOXML font-family class (0..5). */
1168
+ family: number;
1169
+ /** Whether the source carried a `<charset>` element. */
1170
+ hasCharset: boolean;
1171
+ /** OOXML charset codepage id (e.g. 128 = Shift_JIS). */
1172
+ charset: number;
1173
+ /** AARRGGBB literal RGB or compatibility fallback; not a resolved
1174
+ * theme/indexed/auto render colour. */
880
1175
  colorArgb: number;
1176
+ /** Original `<color>` specification, preserved for round-tripping. */
1177
+ color: ColorSpec;
881
1178
  }
882
1179
 
883
1180
  /** Plain-data shape of a fill record. Mirrors `formulon::io::FillRecord`. */
884
1181
  export interface FillRecord {
885
1182
  /** OOXML pattern ordinal: 0=none, 1=solid, 2..18=standard pattern set. */
886
1183
  pattern: number;
887
- /** Foreground AARRGGBB colour. */
1184
+ /** Foreground literal RGB or compatibility fallback. */
888
1185
  fgArgb: number;
889
- /** Background AARRGGBB colour. */
1186
+ /** Background literal RGB or compatibility fallback. */
890
1187
  bgArgb: number;
1188
+ /** Original `<fgColor>` specification, preserved for round-tripping. */
1189
+ fg: ColorSpec;
1190
+ /** Original `<bgColor>` specification, preserved for round-tripping. */
1191
+ bg: ColorSpec;
891
1192
  }
892
1193
 
893
1194
  /** One side of a `BorderRecord`. */
894
1195
  export interface BorderSide {
895
1196
  /** OOXML border-style ordinal: 0=none, 1=thin, ..., 13=slantDashDot. */
896
1197
  style: number;
897
- /** AARRGGBB packed colour. */
1198
+ /** AARRGGBB literal RGB or compatibility fallback; not a resolved
1199
+ * theme/indexed/auto render colour. */
898
1200
  colorArgb: number;
1201
+ /** Original `<color>` specification, preserved for round-tripping. */
1202
+ color: ColorSpec;
899
1203
  }
900
1204
 
901
1205
  /** Plain-data shape of a border record. Mirrors `formulon::io::BorderRecord`. */
@@ -920,6 +1224,32 @@ export interface CellXf {
920
1224
  /** 0=top, 1=center, 2=bottom, 3=justify, 4=distributed. */
921
1225
  verticalAlign: number;
922
1226
  wrapText: boolean;
1227
+ /** OOXML `justifyLastLine`; effective with distributed alignment. Defaults to false. */
1228
+ justifyLastLine?: boolean;
1229
+ /** Whether to preserve an explicit alignment child. Omit to infer from supplied alignment fields. */
1230
+ hasAlignment?: boolean;
1231
+ /** Whether `horizontalAlign` was explicitly supplied; defaults to inference. */
1232
+ hasHorizontalAlign?: boolean;
1233
+ /** Whether `verticalAlign` was explicitly supplied; defaults to inference. */
1234
+ hasVerticalAlign?: boolean;
1235
+ /** Whether `wrapText` was explicitly supplied; defaults to inference. */
1236
+ hasWrapText?: boolean;
1237
+ /** Whether `justifyLastLine` was explicitly supplied; defaults to inference. */
1238
+ hasJustifyLastLine?: boolean;
1239
+ /** OOXML `textRotation` (0..180 or 255). Omitted when absent. */
1240
+ textRotation?: number;
1241
+ /** OOXML `indent` (0..255). Omitted when absent. */
1242
+ indent?: number;
1243
+ /** OOXML signed `relativeIndent`. Omitted when absent. */
1244
+ relativeIndent?: number;
1245
+ /** OOXML `shrinkToFit`; omitted when absent so explicit false is retained. */
1246
+ shrinkToFit?: boolean;
1247
+ /** OOXML `readingOrder` (0=context, 1=LTR, 2=RTL). Omitted when absent. */
1248
+ readingOrder?: number;
1249
+ /** Index of the named style in `<cellStyleXfs>` this format inherits from.
1250
+ * Only meaningful for `addXf`; must name an entry created by
1251
+ * `addCellStyleXf`. Defaults to 0. */
1252
+ xfId?: number;
923
1253
  }
924
1254
 
925
1255
  /** Return type of `Workbook.getFont(fontIndex)`. */
@@ -954,6 +1284,10 @@ export interface DxfRecord {
954
1284
  numFmtId: number;
955
1285
  formatCode: string;
956
1286
  };
1287
+ /** Serialized OOXML `<alignment .../>` child; lexical formatting may normalize on load. */
1288
+ alignmentXml?: string;
1289
+ /** Serialized OOXML `<protection .../>` child; lexical formatting may normalize on load. */
1290
+ protectionXml?: string;
957
1291
  }
958
1292
 
959
1293
  export interface DxfResult extends DxfRecord {
@@ -971,9 +1305,20 @@ export interface LambdaTextResult {
971
1305
  text: string;
972
1306
  }
973
1307
 
1308
+ /** Minimum severity for the engine's structured log stream. Mirrors
1309
+ * `fm_log_level_t`. `Off` discards every record and is the default: an
1310
+ * embedded library must not write to the host's stderr unless asked. */
1311
+ export enum LogLevel {
1312
+ Debug = 0,
1313
+ Info = 1,
1314
+ Warn = 2,
1315
+ Error = 3,
1316
+ Off = 4,
1317
+ }
1318
+
974
1319
  /** External-link kinds. Mirrors
975
1320
  * `formulon::io::ExternalLinkRecord::Kind`. */
976
- export const enum ExternalLinkKind {
1321
+ export enum ExternalLinkKind {
977
1322
  Unknown = 0,
978
1323
  ExternalBook = 1,
979
1324
  Ole = 2,
@@ -1032,8 +1377,9 @@ export interface AddStyleResult {
1032
1377
  index: number;
1033
1378
  }
1034
1379
 
1035
- /** Return type of `Workbook.addNumFmt(formatCode)`. The id is either a
1036
- * matched built-in (`0..163`) or a freshly-assigned custom id (`>= 164`). */
1380
+ /** Return type of `Workbook.addNumFmt(formatCode)`. The id may reuse any
1381
+ * existing effective mapping (built-in or custom, including a custom record
1382
+ * overriding a built-in slot), or be a freshly-assigned custom id (`>= 164`). */
1037
1383
  export interface AddNumFmtResult {
1038
1384
  status: Status;
1039
1385
  numFmtId: number;
@@ -1055,10 +1401,178 @@ export interface PartialRecalcResult {
1055
1401
  recomputed: number;
1056
1402
  }
1057
1403
 
1404
+ /** Return type of `Workbook.getIterative()`. */
1405
+ export interface IterativeSettingsResult {
1406
+ status: Status;
1407
+ /** Whether iterative calculation is switched on. */
1408
+ enabled: boolean;
1409
+ /** Stored iteration cap; meaningful even while `enabled` is false. */
1410
+ maxIterations: number;
1411
+ /** Stored convergence threshold; meaningful even while `enabled` is false. */
1412
+ maxChange: number;
1413
+ }
1414
+
1415
+ /** Result of `Workbook.getSheetAutoFilterXml`. The empty `xml` string means
1416
+ * that the sheet has no AutoFilter definition. */
1417
+ export interface SheetAutoFilterXmlResult {
1418
+ status: Status;
1419
+ xml: string;
1420
+ }
1421
+
1422
+ /** Result of the five raw print-settings getters. The empty `xml` string
1423
+ * means the sheet declares no such element. */
1424
+ export interface SheetPrintXmlResult {
1425
+ status: Status;
1426
+ xml: string;
1427
+ }
1428
+
1429
+ /** Result of `Workbook.getSheetPrintArea`. `ranges` is comma-separated A1
1430
+ * (`"A1:F8"`, `"A1:B10,D5:E20"`), empty when no print area is declared. A
1431
+ * whole-axis area reads back expanded to explicit corners. */
1432
+ export interface SheetPrintAreaResult {
1433
+ status: Status;
1434
+ ranges: string;
1435
+ }
1436
+
1437
+ /** Result of `Workbook.getSheetPrintTitles`. Either span is empty when
1438
+ * that axis has no repeat setting. */
1439
+ export interface SheetPrintTitlesResult {
1440
+ status: Status;
1441
+ /** Whole-row span, e.g. `"1:2"`. */
1442
+ repeatRows: string;
1443
+ /** Whole-column span, e.g. `"A:A"`. */
1444
+ repeatCols: string;
1445
+ }
1446
+
1447
+ /** One manual page break. `id` is the 0-based row / column the break
1448
+ * precedes; `min` / `max` bound it on the perpendicular axis. `manual` is
1449
+ * false for a break Excel computed rather than one a user placed. */
1450
+ export interface PageBreak {
1451
+ id: number;
1452
+ min: number;
1453
+ max: number;
1454
+ manual: boolean;
1455
+ }
1456
+
1457
+ /** Result of `Workbook.getSheetRowBreaks` / `getSheetColBreaks`. */
1458
+ export interface SheetPageBreaksResult {
1459
+ status: Status;
1460
+ breaks: PageBreak[];
1461
+ }
1462
+
1463
+ /** Page orientation as `<pageSetup orientation>` encodes it: `0` leaves the
1464
+ * attribute off (the printer default), `1` is portrait, `2` is landscape.
1465
+ *
1466
+ * Declared as a union rather than an `enum` so it stays a compile-time-only
1467
+ * type: there is no runtime table to keep in step across the two packages,
1468
+ * and the three values are the whole domain. */
1469
+ export type Orientation = 0 | 1 | 2;
1470
+
1471
+ /** Partial `<pageSetup>` update. Only the keys present are applied; every
1472
+ * other attribute in the stored XML — including ones this engine does not
1473
+ * model, such as `r:id`, `horizontalDpi` and `copies` — is left alone.
1474
+ *
1475
+ * `fitToPage` is not a `<pageSetup>` attribute: it is routed to
1476
+ * `<sheetPr><pageSetUpPr>`. It selects the fit-to-page mode, and
1477
+ * `fitToWidth` / `fitToHeight` state the target, so "fit onto one page"
1478
+ * needs all three. */
1479
+ export interface PageSetupInput {
1480
+ orientation?: Orientation;
1481
+ /** OOXML paperSize code; 9 = A4. */
1482
+ paperSize?: number;
1483
+ /** Print scale percentage. Outside `[10, 400]` is rejected, not clamped. */
1484
+ scale?: number;
1485
+ fitToWidth?: number;
1486
+ fitToHeight?: number;
1487
+ fitToPage?: boolean;
1488
+ }
1489
+
1490
+ /** Result of `Workbook.getSheetPageSetup`. Every value carries the setting
1491
+ * in force; the `*Stated` flags say whether the XML declares it, which is
1492
+ * the only way to tell `scale="100"` from an absent attribute. */
1493
+ export interface SheetPageSetupResult {
1494
+ status: Status;
1495
+ orientation: Orientation;
1496
+ paperSize: number;
1497
+ scale: number;
1498
+ fitToWidth: number;
1499
+ fitToHeight: number;
1500
+ fitToPage: boolean;
1501
+ orientationStated: boolean;
1502
+ paperSizeStated: boolean;
1503
+ scaleStated: boolean;
1504
+ fitToWidthStated: boolean;
1505
+ fitToHeightStated: boolean;
1506
+ fitToPageStated: boolean;
1507
+ }
1508
+
1509
+ /** Partial `<pageMargins>` update, in inches. A negative, infinite or NaN
1510
+ * margin is rejected: the paginator subtracts these from the paper. */
1511
+ export interface PageMarginsInput {
1512
+ left?: number;
1513
+ right?: number;
1514
+ top?: number;
1515
+ bottom?: number;
1516
+ header?: number;
1517
+ footer?: number;
1518
+ }
1519
+
1520
+ /** Result of `Workbook.getSheetPageMargins`, in inches. */
1521
+ export interface SheetPageMarginsResult {
1522
+ status: Status;
1523
+ left: number;
1524
+ right: number;
1525
+ top: number;
1526
+ bottom: number;
1527
+ header: number;
1528
+ footer: number;
1529
+ leftStated: boolean;
1530
+ rightStated: boolean;
1531
+ topStated: boolean;
1532
+ bottomStated: boolean;
1533
+ headerStated: boolean;
1534
+ footerStated: boolean;
1535
+ }
1536
+
1537
+ /** Partial `<printOptions>` update. */
1538
+ export interface PrintOptionsInput {
1539
+ gridLines?: boolean;
1540
+ headings?: boolean;
1541
+ horizontalCentered?: boolean;
1542
+ verticalCentered?: boolean;
1543
+ }
1544
+
1545
+ /** Partial `<headerFooter>` update.
1546
+ *
1547
+ * Each section is tri-state: omit the key to leave it untouched, pass `""`
1548
+ * to clear it, pass anything else to replace it. Section text is the
1549
+ * decoded string, so Excel's formatting codes go in plainly
1550
+ * (`'&C&"MS Gothic"Report &P/&N'`); the engine applies the XML escaping
1551
+ * that turns each leading `&` into the `&amp;` Excel stores. */
1552
+ export interface HeaderFooterInput {
1553
+ oddHeader?: string;
1554
+ oddFooter?: string;
1555
+ evenHeader?: string;
1556
+ evenFooter?: string;
1557
+ firstHeader?: string;
1558
+ firstFooter?: string;
1559
+ differentOddEven?: boolean;
1560
+ differentFirst?: boolean;
1561
+ scaleWithDoc?: boolean;
1562
+ alignWithMargins?: boolean;
1563
+ }
1564
+
1058
1565
  /** Iterative-solver progress callback. Receives the current
1059
1566
  * iteration number, the maximum residual seen, and the configured
1060
1567
  * iteration cap. Returning `false` (or any falsy value) aborts the
1061
- * solve; returning `true` (or `undefined`) continues. */
1568
+ * solve; returning `true` (or `undefined`) continues.
1569
+ *
1570
+ * Throwing also aborts the solve, and the exception does not reach the
1571
+ * caller: the recalc that ran the callback returns `{ok: false}` with
1572
+ * status 7003 (`kBindingCallbackException`) instead. Cells committed by
1573
+ * the sweeps that already ran keep their values, and the workbook stays
1574
+ * usable — the next recalc behaves as if the aborted one had been
1575
+ * cancelled deliberately. */
1062
1576
  export type IterativeProgressCallback = (
1063
1577
  iteration: number,
1064
1578
  maxResidual: number,
@@ -1074,7 +1588,11 @@ export interface Workbook {
1074
1588
 
1075
1589
  save(): SaveResult;
1076
1590
  /** Serialises using an explicit container `format` (see `WorkbookFormat`). */
1077
- saveEx(format: WorkbookFormat | number): SaveResult;
1591
+ saveAs(format: WorkbookFormat | number): SaveResult;
1592
+ /** Serialises using an explicit format and reports loss/defer counters. */
1593
+ saveWithDiagnostics(format: WorkbookFormat | number): SaveDiagnosticsResult;
1594
+ /** Returns the loss counters captured when this handle was loaded. */
1595
+ readDiagnostics(): ReadDiagnosticsResult;
1078
1596
  addSheet(name: string): Status;
1079
1597
  /** Removes the sheet at `index`. */
1080
1598
  removeSheet(index: number): Status;
@@ -1137,14 +1655,43 @@ export interface Workbook {
1137
1655
  /** Returns the cell's OOXML phonetic guide (`<rPh>`), or an empty string. */
1138
1656
  getCellPhonetic(sheet: number, row: number, col: number): StringResult;
1139
1657
 
1658
+ /** Recalculates all dirty cells serially on the caller thread.
1659
+ *
1660
+ * Reports status 7003 (`kBindingCallbackException`) when an installed
1661
+ * `IterativeProgressCallback` threw during the pass. */
1140
1662
  recalc(): Status;
1141
- /** Recalculates only cells touched by the supplied viewport. */
1663
+ /**
1664
+ * Recalculates all dirty cells using the parallel SCC scheduler and returns
1665
+ * per-call telemetry. This call is synchronous: it returns after all
1666
+ * workers have joined. `threadCount` must be a finite integer: 0 selects
1667
+ * automatic detection (capped at 8), 1 keeps evaluation on the caller and
1668
+ * starts no workers, and 2..8 set the worker upper bound. Missing,
1669
+ * fractional, non-finite, negative, or above-8 values fail with
1670
+ * `kInvalidArgument`.
1671
+ * The `uint64_t` counters in `stats` are JavaScript numbers and are exact
1672
+ * through `Number.MAX_SAFE_INTEGER` (2^53 - 1).
1673
+ * As with `recalc`, a throwing `IterativeProgressCallback` is reported as
1674
+ * status 7003 with the counters left at zero.
1675
+ */
1676
+ recalcParallel(threadCount: number): ParallelRecalcResult;
1677
+ /** Recalculates only cells touched by the supplied viewport. Reports
1678
+ * status 7003 with `recomputed` at zero when a throwing
1679
+ * `IterativeProgressCallback` cut the pass short. */
1142
1680
  partialRecalc(viewport: RecalcViewport): PartialRecalcResult;
1143
1681
 
1144
1682
  setIterative(enabled: boolean, maxIterations: number, maxChange: number): Status;
1683
+ /** Reads back the stored iterative-calculation settings. The cap and
1684
+ * threshold are the stored values even while `enabled` is false, so a
1685
+ * host can render Excel's iterative-calculation dialog before the user
1686
+ * has switched iteration on. */
1687
+ getIterative(): IterativeSettingsResult;
1145
1688
  /** Installs (or, when passed `null`, clears) a JS callback invoked
1146
- * after each Gauss-Seidel sweep. Only one callback can be active per
1147
- * WASM instance — installing a new one displaces the previous. */
1689
+ * after each Gauss-Seidel sweep. The callback belongs to this
1690
+ * `Workbook`: installing one on another instance leaves this one's
1691
+ * registration alone.
1692
+ *
1693
+ * A value that is not callable is accepted here and reported when the
1694
+ * solver tries to use it, the same way a throwing callback is. */
1148
1695
  setIterativeProgress(callback: IterativeProgressCallback | null): Status;
1149
1696
 
1150
1697
  /**
@@ -1158,12 +1705,62 @@ export interface Workbook {
1158
1705
  calcMode(): CalcMode;
1159
1706
  setCalcMode(mode: CalcMode): Status;
1160
1707
 
1708
+ /**
1709
+ * The workbook's pinned wall-clock reading, or `null` when it follows the
1710
+ * host clock (the default).
1711
+ *
1712
+ * Pinning gives `NOW()`, `TODAY()` and the pivot relative-period filters
1713
+ * ("this month", "year to date", ...) one instant to agree on. Without a
1714
+ * pin each reads the clock independently, which makes a recalc internally
1715
+ * inconsistent across a midnight boundary and makes any such result
1716
+ * untestable.
1717
+ *
1718
+ * Local civil fields are carried rather than a timestamp so the reading has
1719
+ * no residual timezone interpretation: the same values reproduce the same
1720
+ * results in any zone. This is model state, not file state — `save()` does
1721
+ * not record it and a reloaded workbook comes back unpinned.
1722
+ *
1723
+ * Cached formula values are not recomputed by `setPinnedNow`; drive
1724
+ * `recalc()` to see the pin take effect on existing cells.
1725
+ *
1726
+ * `setPinnedNow` returns `kInvalidArgument` unless `year` is in
1727
+ * `[1900, 9999]`, `month` in `[1, 12]`, `day` within that month's real
1728
+ * length, `hour` in `[0, 23]`, and `minute` / `second` in `[0, 59]`. The
1729
+ * pin is a calendar instant, not a normalising constructor: a month of 13
1730
+ * is rejected rather than rolled into the next year.
1731
+ */
1732
+ pinnedNow(): CivilTime | null;
1733
+ setPinnedNow(year: number, month: number, day: number, hour: number, minute: number, second: number): Status;
1734
+ clearPinnedNow(): Status;
1735
+
1161
1736
  /**
1162
1737
  * Full formula-behaviour profile id. Defaults to `win-365-ja_JP`.
1163
1738
  */
1164
1739
  excelProfileId(): ExcelProfileId;
1165
1740
  setExcelProfileId(profileId: ExcelProfileId): Status;
1166
1741
 
1742
+ /**
1743
+ * The four structural edits move every structure the engine models:
1744
+ * cells, formulas, merges, conditional-format ranges, validations,
1745
+ * 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.
1754
+ *
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.
1762
+ */
1763
+
1167
1764
  /** Inserts `count` rows at `row` on `sheet` and rewrites cross-workbook
1168
1765
  * references to follow the shift. */
1169
1766
  insertRows(sheet: number, row: number, count: number): Status;
@@ -1189,6 +1786,17 @@ export interface Workbook {
1189
1786
 
1190
1787
  tableCount(): number;
1191
1788
  tableAt(idx: number): TableEntry;
1789
+ createTable(input: TableInput): AddStyleResult;
1790
+ /** Partially updates a table. Omitted fields preserve their current
1791
+ * values. A supplied `ref` must keep the table's existing column count;
1792
+ * an empty `styleName` clears the style. */
1793
+ updateTable(idx: number, input: TableUpdateInput): Status;
1794
+ removeTable(idx: number): Status;
1795
+
1796
+ /** Reads the complete worksheet-level `<autoFilter>` XML fragment. */
1797
+ getSheetAutoFilterXml(sheet: number): SheetAutoFilterXmlResult;
1798
+ /** Replaces the worksheet-level `<autoFilter>` XML fragment; empty clears it. */
1799
+ setSheetAutoFilterXml(sheet: number, xml: string): Status;
1192
1800
 
1193
1801
  passthroughCount(): number;
1194
1802
  passthroughAt(idx: number): PassthroughEntry;
@@ -1297,8 +1905,20 @@ export interface Workbook {
1297
1905
  pivotFieldAddAggregation(sheet: number, pivotIdx: number, fieldIdx: number, agg: PivotAggregation): Status;
1298
1906
  /** Drops every aggregation from pivot field `fieldIdx`. */
1299
1907
  pivotFieldClearAggregations(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1300
- /** Appends a manual-filter item to pivot field `fieldIdx`. */
1908
+ /** Appends a manual-filter item to pivot field `fieldIdx`, addressed by
1909
+ * its label. The item carries no cache binding, so the filter engine
1910
+ * matches source records by comparing their rendered label against
1911
+ * `name`. An empty `name` therefore cannot express the blank item,
1912
+ * which has no label of its own; use `pivotFieldAddItemAt`. */
1301
1913
  pivotFieldAddItem(sheet: number, pivotIdx: number, fieldIdx: number, name: string, visible: boolean): Status;
1914
+ /** Appends a manual-filter item to pivot field `fieldIdx`, addressed by
1915
+ * its position in the bound cache field's shared items -- the same
1916
+ * index space as OOXML `<item x="N">`. The label is resolved from that
1917
+ * shared item, which makes this the form that can express the blank
1918
+ * item. `cacheIndex` is not validated: the cache field may be filled in
1919
+ * after the pivot definition, and an index that resolves to nothing
1920
+ * yields an item with an empty label that filters nothing. */
1921
+ pivotFieldAddItemAt(sheet: number, pivotIdx: number, fieldIdx: number, cacheIndex: number, visible: boolean): Status;
1302
1922
  /** Drops every manual-filter item from pivot field `fieldIdx`. */
1303
1923
  pivotFieldClearItems(sheet: number, pivotIdx: number, fieldIdx: number): Status;
1304
1924
  /** Toggles the visibility of item `itemIdx` on field `fieldIdx`. */
@@ -1345,18 +1965,25 @@ export interface Workbook {
1345
1965
  /** Replaces the data-field entry at `dataFieldIdx` in place. */
1346
1966
  pivotDataFieldSet(sheet: number, pivotIdx: number, dataFieldIdx: number, spec: PivotDataFieldSpec): Status;
1347
1967
 
1348
- /** Number of active (slicer-applied) filters on the pivot. */
1968
+ /** Number of active (slicer-applied) filters on the pivot. Counts only
1969
+ * the entries this session added -- see {@link PivotFilterResult}. */
1349
1970
  pivotFilterCount(sheet: number, pivotIdx: number): number;
1350
- /** Appends an active filter. */
1971
+ /** Appends an active filter. The entry is session state and is not
1972
+ * written by `save`; see {@link PivotFilterResult}. */
1351
1973
  pivotFilterAdd(sheet: number, pivotIdx: number, spec: PivotFilterSpec): Status;
1974
+ /** Reads the active filter at `filterIdx`. The list is session state:
1975
+ * see {@link PivotFilterResult}. */
1976
+ pivotFilterAt(sheet: number, pivotIdx: number, filterIdx: number): PivotFilterResult;
1352
1977
  /** Drops every active filter from the pivot. */
1353
1978
  pivotFilterClear(sheet: number, pivotIdx: number): Status;
1354
1979
  /** Removes the active filter at `filterIdx`. */
1355
1980
  pivotFilterRemoveAt(sheet: number, pivotIdx: number, filterIdx: number): Status;
1356
1981
 
1357
1982
  /** Evaluates every CF block on `sheet` against the inclusive range
1358
- * `[(firstRow, firstCol), (lastRow, lastCol)]`. Pass `NaN` for
1359
- * `todaySerial` to disable `TimePeriod` rules. */
1983
+ * `[(firstRow, firstCol), (lastRow, lastCol)]`. `todaySerial` pins the
1984
+ * date basis for `TimePeriod` rules; pass `NaN` to disable them (no
1985
+ * `TimePeriod` rule then matches). `0` does *not* disable them -- it is
1986
+ * the valid serial for 1899-12-30. */
1360
1987
  evaluateCfRange(
1361
1988
  sheet: number,
1362
1989
  firstRow: number,
@@ -1369,6 +1996,74 @@ export interface Workbook {
1369
1996
  /** Computes print-area page breaks and physical page count for `sheet`. */
1370
1997
  paginate(sheet: number): PaginationResult;
1371
1998
 
1999
+ /** Reads the worksheet's `<pageSetup>` fragment; empty when absent. */
2000
+ getSheetPageSetupXml(sheet: number): SheetPrintXmlResult;
2001
+ /** Replaces `<pageSetup>`; empty removes it and restores the defaults.
2002
+ * A fragment carrying `r:id` is rejected unless the sheet already has a
2003
+ * printerSettings part, since the reference would otherwise dangle. */
2004
+ setSheetPageSetupXml(sheet: number, xml: string): Status;
2005
+ /** Reads the worksheet's `<pageMargins>` fragment; empty when absent. */
2006
+ getSheetPageMarginsXml(sheet: number): SheetPrintXmlResult;
2007
+ /** Replaces `<pageMargins>`; empty removes it. */
2008
+ setSheetPageMarginsXml(sheet: number, xml: string): Status;
2009
+ /** Reads the worksheet's `<printOptions>` fragment; empty when absent. */
2010
+ getSheetPrintOptionsXml(sheet: number): SheetPrintXmlResult;
2011
+ /** Replaces `<printOptions>`; empty removes it. */
2012
+ setSheetPrintOptionsXml(sheet: number, xml: string): Status;
2013
+ /** Reads the worksheet's `<headerFooter>` fragment; empty when absent. */
2014
+ getSheetHeaderFooterXml(sheet: number): SheetPrintXmlResult;
2015
+ /** Replaces `<headerFooter>`; empty removes it. Header codes live in XML
2016
+ * element text, so a hand-built fragment writes them escaped
2017
+ * (`<oddHeader>&amp;C...</oddHeader>`); `setSheetHeaderFooter` takes the
2018
+ * decoded text instead. */
2019
+ setSheetHeaderFooterXml(sheet: number, xml: string): Status;
2020
+ /** Reads the worksheet's `<sheetPr>` fragment; empty when absent. It also
2021
+ * carries the tab colour and VBA code name, not just print settings. */
2022
+ getSheetSheetPrXml(sheet: number): SheetPrintXmlResult;
2023
+ /** Replaces `<sheetPr>`; empty removes it. */
2024
+ setSheetSheetPrXml(sheet: number, xml: string): Status;
2025
+ /** Sets or clears `<sheetPr><pageSetUpPr fitToPage>` without disturbing
2026
+ * anything else `<sheetPr>` carries. */
2027
+ setSheetFitToPage(sheet: number, enabled: boolean): Status;
2028
+
2029
+ /** Reads `_xlnm.Print_Area` as comma-separated A1 ranges. */
2030
+ getSheetPrintArea(sheet: number): SheetPrintAreaResult;
2031
+ /** Writes `_xlnm.Print_Area` from one or more comma-separated A1 ranges
2032
+ * (`"A1:F8"`, `"A1:B10,D5:E20"`, `"A:D"`). Empty removes it. */
2033
+ setSheetPrintArea(sheet: number, rangesA1: string): Status;
2034
+ /** Reads `_xlnm.Print_Titles` as a row span and a column span. */
2035
+ getSheetPrintTitles(sheet: number): SheetPrintTitlesResult;
2036
+ /** Writes `_xlnm.Print_Titles`. Both empty removes it. */
2037
+ setSheetPrintTitles(sheet: number, repeatRows: string, repeatCols: string): Status;
2038
+
2039
+ /** Upserts a row break before `row`, spanning the whole sheet. */
2040
+ addSheetRowBreak(sheet: number, row: number, manual: boolean): Status;
2041
+ /** Upserts a column break before `col`, spanning the whole sheet. */
2042
+ addSheetColBreak(sheet: number, col: number, manual: boolean): Status;
2043
+ /** Removes the row break at `row`. An absent break is a no-op. */
2044
+ removeSheetRowBreak(sheet: number, row: number): Status;
2045
+ /** Removes the column break at `col`. An absent break is a no-op. */
2046
+ removeSheetColBreak(sheet: number, col: number): Status;
2047
+ /** Removes every manual break on both axes. */
2048
+ clearSheetBreaks(sheet: number): Status;
2049
+ /** Returns the row breaks, ascending by row. */
2050
+ getSheetRowBreaks(sheet: number): SheetPageBreaksResult;
2051
+ /** Returns the column breaks, ascending by column. */
2052
+ getSheetColBreaks(sheet: number): SheetPageBreaksResult;
2053
+
2054
+ /** Applies a partial `<pageSetup>` update. */
2055
+ setSheetPageSetup(sheet: number, setup: PageSetupInput): Status;
2056
+ /** Applies a partial `<pageMargins>` update, in inches. */
2057
+ setSheetPageMargins(sheet: number, margins: PageMarginsInput): Status;
2058
+ /** Applies a partial `<printOptions>` update. */
2059
+ setSheetPrintOptions(sheet: number, options: PrintOptionsInput): Status;
2060
+ /** Applies a partial `<headerFooter>` update. */
2061
+ setSheetHeaderFooter(sheet: number, headerFooter: HeaderFooterInput): Status;
2062
+ /** Reads the effective page setup and which attributes state it. */
2063
+ getSheetPageSetup(sheet: number): SheetPageSetupResult;
2064
+ /** Reads the effective page margins, in inches. */
2065
+ getSheetPageMargins(sheet: number): SheetPageMarginsResult;
2066
+
1372
2067
  /** Reads the full per-sheet view (zoom, freeze, tab-hidden, and the
1373
2068
  * display / orientation flags). */
1374
2069
  getSheetView(sheet: number): SheetViewResult;
@@ -1376,8 +2071,18 @@ export interface Workbook {
1376
2071
  setSheetZoom(sheet: number, zoomScale: number): Status;
1377
2072
  /** Sets the frozen pane in `(rows, cols)`. */
1378
2073
  setSheetFreeze(sheet: number, freezeRows: number, freezeCols: number): Status;
1379
- /** Sets the sheet tab's hidden flag. */
2074
+ /** Sets the sheet tab's hidden flag — the two-state view of
2075
+ * `setSheetVisibility`. `true` on an already very-hidden sheet leaves
2076
+ * it very-hidden rather than demoting it, since "hidden" says nothing
2077
+ * that sheet does not already satisfy; `false` shows it from either
2078
+ * hidden state. */
1380
2079
  setSheetTabHidden(sheet: number, hidden: boolean): Status;
2080
+ /** Sets the sheet tab's visibility to one of the three states. The only
2081
+ * way to newly state `SheetVisibility.VeryHidden`, and the only way to
2082
+ * demote a very-hidden sheet to plain hidden; `setSheetTabHidden` can
2083
+ * express neither. A value outside `SheetVisibility` fails with
2084
+ * `kInvalidArgument` and leaves the sheet unchanged. */
2085
+ setSheetVisibility(sheet: number, visibility: SheetVisibility): Status;
1381
2086
  /** Sets the sheet's `showGridLines` flag. */
1382
2087
  setSheetShowGridLines(sheet: number, show: boolean): Status;
1383
2088
  /** Sets the sheet's `showRowColHeaders` flag. */
@@ -1426,13 +2131,23 @@ export interface Workbook {
1426
2131
  getCellXfIndex(sheet: number, row: number, col: number): CellXfIndexResult;
1427
2132
  /** Persists `xfIndex` on the cell at `(sheet, row, col)`. */
1428
2133
  setCellXfIndex(sheet: number, row: number, col: number, xfIndex: number): Status;
2134
+ /** Applies `xfIndex` across an inclusive rectangle, materialising blank
2135
+ * cells so an empty ruled box renders. Saves one call per cell. */
2136
+ setRangeXfIndex(
2137
+ sheet: number,
2138
+ firstRow: number,
2139
+ firstCol: number,
2140
+ lastRow: number,
2141
+ lastCol: number,
2142
+ xfIndex: number,
2143
+ ): Status;
1429
2144
  /** Returns the resolved XF record at `xfIndex`. */
1430
2145
  getCellXf(xfIndex: number): CellXfResult;
1431
- /** Returns the resolved font record at `fontIndex`. */
2146
+ /** Returns the font record at `fontIndex`, including its ColorSpec selector. */
1432
2147
  getFont(fontIndex: number): FontResult;
1433
- /** Returns the resolved fill record at `fillIndex`. */
2148
+ /** Returns the fill record at `fillIndex`, including its ColorSpec selectors. */
1434
2149
  getFill(fillIndex: number): FillResult;
1435
- /** Returns the resolved border record at `borderIndex`. */
2150
+ /** Returns the border record at `borderIndex`, including its ColorSpec selectors. */
1436
2151
  getBorder(borderIndex: number): BorderResult;
1437
2152
  /** Returns the format string registered for `numFmtId`. */
1438
2153
  getNumFmt(numFmtId: number): NumFmtResult;
@@ -1446,9 +2161,13 @@ export interface Workbook {
1446
2161
  addFill(record: FillRecord): AddStyleResult;
1447
2162
  /** Adds a border (deduplicating against existing entries). */
1448
2163
  addBorder(record: BorderRecord): AddStyleResult;
1449
- /** Adds a number-format code. Built-in matches return the built-in id
1450
- * without modifying the table; custom codes are appended at
1451
- * `max(existing_custom_id, 163) + 1`. */
2164
+ /** Adds a number-format code. An existing effective mapping is reused,
2165
+ * including an existing custom record; a built-in id is reused without
2166
+ * modifying the table only when its current effective mapping matches the
2167
+ * code. Otherwise custom codes are appended at
2168
+ * `max(existing_custom_id, 163) + 1`. Effective mappings use the first
2169
+ * valid custom record for an id in document order, then a non-empty
2170
+ * built-in code. */
1452
2171
  addNumFmt(formatCode: string): AddNumFmtResult;
1453
2172
  /** Adds an `<xf>` record (deduplicating against existing entries).
1454
2173
  * Out-of-range font/fill/border indices or unregistered `numFmtId`
@@ -1483,6 +2202,14 @@ export interface Workbook {
1483
2202
  /** Returns the named-style xf record at `index`. Output shape mirrors
1484
2203
  * `getCellXf`. */
1485
2204
  getCellStyleXf(index: number): CellXfResult;
2205
+ /** Appends (deduplicating) a named-style xf and returns its
2206
+ * `<cellStyleXfs>` index, which is what `setCellStyle` and
2207
+ * `CellXf.xfId` reference. */
2208
+ addCellStyleXf(record: CellXf): AddStyleResult;
2209
+ /** Adds or replaces the `<cellStyle>` entry named `name`. `builtinId` is
2210
+ * an OOXML ordinal `0..47`, or `0xFFFFFFFF` for a custom style; it is
2211
+ * required because the binding takes a fixed argument count. */
2212
+ setCellStyle(name: string, xfId: number, builtinId: number): Status;
1486
2213
 
1487
2214
  /** Returns every external-link record carried by the workbook in
1488
2215
  * `<externalReferences>` document order. Empty for fresh workbooks
@@ -1522,6 +2249,19 @@ export interface Workbook {
1522
2249
  tooltip: string,
1523
2250
  location: string,
1524
2251
  ): Status;
2252
+ /** Appends a hyperlink covering the inclusive rectangle from `(row, col)`
2253
+ * through `(lastRow, lastCol)`. */
2254
+ addHyperlinkRange(
2255
+ sheet: number,
2256
+ row: number,
2257
+ col: number,
2258
+ lastRow: number,
2259
+ lastCol: number,
2260
+ target: string,
2261
+ display: string,
2262
+ tooltip: string,
2263
+ location: string,
2264
+ ): Status;
1525
2265
  /** Removes every hyperlink anchored at `(row, col)`. No-op when none match. */
1526
2266
  removeHyperlink(sheet: number, row: number, col: number): Status;
1527
2267
  /** Removes the hyperlink at `index`. Returns kInvalidArgument if `index` is out of range. */
@@ -1572,24 +2312,25 @@ export interface Workbook {
1572
2312
 
1573
2313
  /** Returns metadata for the function `name` (case-insensitive). When
1574
2314
  * the function is unknown, returns `{ok: false}`. `locale` selects
1575
- * the catalog locale (`0` = `en-US`, `1` = `ja-JP`); description /
1576
- * signature fields are populated only when the locale metadata table
1577
- * has an entry. */
2315
+ * the catalog locale (`0` = `en-US`, `1` = `ja-JP`) and is validated,
2316
+ * but does not change the result: the description / signature fields
2317
+ * are always `undefined` (see {@link FunctionMetadataResult}). */
1578
2318
  functionMetadata(name: string, locale: number): FunctionMetadataResult;
1579
2319
  /** Returns every registered function's canonical name in ascending
1580
2320
  * sort order. */
1581
2321
  functionNames(): ReadonlyArray<string>;
1582
2322
 
1583
2323
  /** Returns the localized display name for the canonical function
1584
- * `canonicalName` in `locale`. Returns the canonical name unchanged
1585
- * when the locale's alias table is empty (currently always for
1586
- * non-`en-US` locales). Returns the empty string when the canonical
1587
- * name does not match a registered function. */
2324
+ * `canonicalName` in `locale`. No alias table exists in any locale,
2325
+ * 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. */
1588
2329
  localizeFunctionName(canonicalName: string, locale: number): string;
1589
2330
  /** Inverse of `localizeFunctionName`: returns the canonical English
1590
- * name for the localized function `localizedName`. Falls through to
1591
- * case-insensitive canonical-name matching when no alias is
1592
- * registered. Returns the empty string when no function matches. */
2331
+ * name for the localized function `localizedName`. With no alias
2332
+ * table this is a case-insensitive canonical-name match, in every
2333
+ * locale. Returns the empty string when no function matches. */
1593
2334
  canonicalizeFunctionName(localizedName: string, locale: number): string;
1594
2335
 
1595
2336
  /** Returns dynamic-array spill info for `(sheet, row, col)`.
@@ -1617,8 +2358,12 @@ export interface WorkbookCtor {
1617
2358
  export interface FormulonModule {
1618
2359
  Workbook: WorkbookCtor;
1619
2360
 
1620
- /** Convenience: evaluates a single formula in a fresh workbook
1621
- * (place at `Sheet1!A1`, recalc, return the cached value). */
2361
+ /** Convenience: evaluates `formula` read-only against a fresh
2362
+ * single-sheet workbook, anchored at `Sheet1!A1`. Nothing is written
2363
+ * and no recalc runs, so an anchor-referencing formula such as `=A1`
2364
+ * or `=COUNTA(A1)` reads the blank anchor rather than becoming a
2365
+ * self-reference. An array result is reduced to its top-left element;
2366
+ * use `Workbook.evaluateFormulaArray` for the whole grid. */
1622
2367
  evalFormula(formula: string): EvalResult;
1623
2368
 
1624
2369
  /** Library version string (UTF-8). */
@@ -1638,6 +2383,27 @@ export interface FormulonModule {
1638
2383
 
1639
2384
  /** Most-recent thread-local error context. */
1640
2385
  lastErrorContext(): string;
2386
+
2387
+ /** Sets the engine's minimum structured-log severity (a `LogLevel`
2388
+ * ordinal). This is **process-wide** state, not per `Workbook`. The
2389
+ * default is `LogLevel.Off`, under which the engine writes nothing to
2390
+ * stderr and invokes no sink. */
2391
+ setLogMinLevel(level: number): Status;
2392
+
2393
+ /** Routes structured-log records to `sink`, or restores the (silent at
2394
+ * the default threshold) stderr fallback when `sink` is `null`.
2395
+ * **Process-wide** state, not per `Workbook`.
2396
+ *
2397
+ * `sink` receives one complete JSON record as raw bytes -- the C ABI
2398
+ * hands the binding a length-delimited range, never a NUL-terminated
2399
+ * string. The view is only valid for the duration of the call; copy it
2400
+ * (`new Uint8Array(record)`) or decode it (`new TextDecoder().decode(
2401
+ * record)`) before returning.
2402
+ *
2403
+ * A sink that throws has its exception dropped and the record lost;
2404
+ * the call that emitted it is unaffected. Records come from arbitrary
2405
+ * depth inside the engine, so there is nowhere to report it. */
2406
+ setLogSink(sink: ((record: Uint8Array) => void) | null): Status;
1641
2407
  }
1642
2408
 
1643
2409
  /** Optional Emscripten module-init overrides. Pass to the factory to