@libraz/formulon 0.9.6 → 0.10.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.
- package/README.md +41 -7
- package/dist/formulon.d.ts +538 -90
- package/dist/formulon.js +99 -18
- package/dist/formulon.wasm +0 -0
- package/dist/formulon_core.js +2 -0
- package/package.json +1 -1
package/dist/formulon.d.ts
CHANGED
|
@@ -1,4 +1,3 @@
|
|
|
1
|
-
// Copyright 2026 libraz. Licensed under the Apache License, Version 2.0.
|
|
2
1
|
//
|
|
3
2
|
// Hand-written TypeScript declarations for the Formulon WASM bindings.
|
|
4
3
|
//
|
|
@@ -34,6 +33,29 @@ export interface Status {
|
|
|
34
33
|
context: string;
|
|
35
34
|
}
|
|
36
35
|
|
|
36
|
+
/** Per-call telemetry returned by `Workbook.recalcParallel`. The five
|
|
37
|
+
* scheduler counters are `uint64_t` in the C ABI but are exposed as
|
|
38
|
+
* JavaScript `number` values by the WASM binding. They are exact through
|
|
39
|
+
* `Number.MAX_SAFE_INTEGER` (2^53 - 1). */
|
|
40
|
+
export interface ParallelRecalcStats {
|
|
41
|
+
cellsEvaluated: number;
|
|
42
|
+
sccsProcessed: number;
|
|
43
|
+
parallelSteps: number;
|
|
44
|
+
serialFallbackSteps: number;
|
|
45
|
+
cycleRecoveries: number;
|
|
46
|
+
workerThreadsStarted: number;
|
|
47
|
+
workerThreadsUsed: number;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** `{ status, stats }` returned by `Workbook.recalcParallel`. */
|
|
51
|
+
export interface ParallelRecalcResult {
|
|
52
|
+
status: Status;
|
|
53
|
+
stats: ParallelRecalcStats;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** A JS array with the status of the list enumeration that produced it. */
|
|
57
|
+
export type ListResult<T> = ReadonlyArray<T> & { readonly status: Status };
|
|
58
|
+
|
|
37
59
|
/** Flattened mirror of `fm_value_t`. Only the field selected by `kind`
|
|
38
60
|
* is meaningful; the others carry default-zero values. */
|
|
39
61
|
export interface Value {
|
|
@@ -73,14 +95,65 @@ export interface EvalArrayResult {
|
|
|
73
95
|
cells: Value[][];
|
|
74
96
|
}
|
|
75
97
|
|
|
76
|
-
/** Return type of `Workbook.save()` / `Workbook.
|
|
98
|
+
/** Return type of `Workbook.save()` / `Workbook.saveAs(format)`. */
|
|
77
99
|
export interface SaveResult {
|
|
78
100
|
status: Status;
|
|
79
101
|
/** Freshly-allocated `Uint8Array` on success; `null` on failure. */
|
|
80
102
|
bytes: Uint8Array | null;
|
|
81
103
|
}
|
|
82
104
|
|
|
83
|
-
/**
|
|
105
|
+
/**
|
|
106
|
+
* Return type of `Workbook.saveWithDiagnostics(format)`.
|
|
107
|
+
*
|
|
108
|
+
* A field means the same thing whichever container was written; where the
|
|
109
|
+
* underlying event exists in only one container, the other simply never
|
|
110
|
+
* raises it. Coverage is partial by design — an all-zero result means
|
|
111
|
+
* none of the losses below occurred, not that nothing was logged.
|
|
112
|
+
*
|
|
113
|
+
* Summing these does NOT give "how many things did I lose":
|
|
114
|
+
* `droppedPartCount` and `droppedRelationshipCount` both rise for one
|
|
115
|
+
* dropped part.
|
|
116
|
+
*/
|
|
117
|
+
export interface SaveDiagnosticsResult extends SaveResult {
|
|
118
|
+
/** Formula cells emitted as cached literals. Always zero for XLSX. */
|
|
119
|
+
downgradedFormulaCount: number;
|
|
120
|
+
/** Sheet features not lowered to records. Always zero for XLSX. */
|
|
121
|
+
deferredFeatureCount: number;
|
|
122
|
+
/** Passthrough parts dropped for colliding with a generated path, or
|
|
123
|
+
* for two entries claiming one path. Both containers. */
|
|
124
|
+
droppedPartCount: number;
|
|
125
|
+
/** Relationships dropped because their target part is gone. Both
|
|
126
|
+
* containers, at package / workbook / (XLSB) sheet scope. Rises with
|
|
127
|
+
* `droppedPartCount` for one dropped part — do not add them. */
|
|
128
|
+
droppedRelationshipCount: number;
|
|
129
|
+
/** Tables emitted under a writer-assigned id. Always zero for XLSB. */
|
|
130
|
+
renumberedPartCount: number;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Return type of `Workbook.readDiagnostics()`. Same contract as
|
|
135
|
+
* `SaveDiagnosticsResult`: one meaning per field across both containers,
|
|
136
|
+
* partial coverage by design.
|
|
137
|
+
*/
|
|
138
|
+
export interface ReadDiagnosticsResult {
|
|
139
|
+
status: Status;
|
|
140
|
+
/** Formula cells whose stored formula could not be decoded. XLSB only. */
|
|
141
|
+
undecodedFormulaCount: number;
|
|
142
|
+
/** Defined names skipped for the same reason. XLSB only. */
|
|
143
|
+
undecodedDefinedNameCount: number;
|
|
144
|
+
/** Package parts whose content type could not be resolved, so they were
|
|
145
|
+
* not decoded. XLSB only — the XLSX reader keeps unmodelled parts as
|
|
146
|
+
* passthrough instead of dropping them. */
|
|
147
|
+
undecodedPartCount: number;
|
|
148
|
+
/** Presentation-overlay entries dropped for an unusable reference: one
|
|
149
|
+
* per merge / hyperlink / data validation, one per conditional-format
|
|
150
|
+
* block (a block can carry several rules). XLSX only. */
|
|
151
|
+
skippedFeatureCount: number;
|
|
152
|
+
/** Workbook parts whose content type was unrecognised. Max 1. XLSX only. */
|
|
153
|
+
unknownContentTypeCount: number;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/** `fm_workbook_format_t` ordinals: container format for `saveAs`. */
|
|
84
157
|
export enum WorkbookFormat {
|
|
85
158
|
Unknown = 0,
|
|
86
159
|
Xlsx = 1,
|
|
@@ -96,35 +169,61 @@ export interface StringResult {
|
|
|
96
169
|
/** Return type of `Workbook.cellAt(sheet, idx)`. */
|
|
97
170
|
export interface CellEntry {
|
|
98
171
|
status: Status;
|
|
99
|
-
row
|
|
100
|
-
col
|
|
172
|
+
row?: number;
|
|
173
|
+
col?: number;
|
|
101
174
|
/** Raw formula text, or `null` for pure literals. */
|
|
102
|
-
formula
|
|
103
|
-
value
|
|
175
|
+
formula?: string | null;
|
|
176
|
+
value?: Value;
|
|
104
177
|
}
|
|
105
178
|
|
|
106
179
|
/** Return type of `Workbook.definedNameAt(idx)`. */
|
|
107
180
|
export interface DefinedNameEntry {
|
|
108
181
|
status: Status;
|
|
109
|
-
name
|
|
110
|
-
formula
|
|
182
|
+
name?: string;
|
|
183
|
+
formula?: string;
|
|
111
184
|
/** -1 for workbook scope; otherwise a 0-based sheet index. */
|
|
112
|
-
localSheetId
|
|
185
|
+
localSheetId?: number;
|
|
113
186
|
}
|
|
114
187
|
|
|
115
188
|
/** Return type of `Workbook.tableAt(idx)`. */
|
|
116
189
|
export interface TableEntry {
|
|
117
190
|
status: Status;
|
|
118
|
-
name
|
|
119
|
-
displayName
|
|
120
|
-
ref
|
|
191
|
+
name?: string;
|
|
192
|
+
displayName?: string;
|
|
193
|
+
ref?: string;
|
|
194
|
+
sheetIndex?: number;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/** Authoring input for a worksheet table. `columns` must have exactly one
|
|
198
|
+
* name per column in `ref`; `styleName` follows Excel's built-in TableStyle
|
|
199
|
+
* names. With `headerRow` (the default), the caller still writes the header
|
|
200
|
+
* cells: Excel expects the first row of `ref` to hold the column names. */
|
|
201
|
+
export interface TableInput {
|
|
121
202
|
sheetIndex: number;
|
|
203
|
+
ref: string;
|
|
204
|
+
name: string;
|
|
205
|
+
displayName?: string;
|
|
206
|
+
columns: string[];
|
|
207
|
+
styleName?: string;
|
|
208
|
+
headerRow?: boolean;
|
|
209
|
+
totalsRow?: boolean;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** Partial table metadata update. Omitted fields preserve their existing
|
|
213
|
+
* values; an empty `styleName` explicitly removes the table style. When
|
|
214
|
+
* omitted, `ref` also preserves the current range. `headerRow` and
|
|
215
|
+
* `totalsRow` update their flags only when supplied. */
|
|
216
|
+
export interface TableUpdateInput {
|
|
217
|
+
ref?: string;
|
|
218
|
+
styleName?: string;
|
|
219
|
+
headerRow?: boolean;
|
|
220
|
+
totalsRow?: boolean;
|
|
122
221
|
}
|
|
123
222
|
|
|
124
223
|
/** Return type of `Workbook.passthroughAt(idx)`. */
|
|
125
224
|
export interface PassthroughEntry {
|
|
126
225
|
status: Status;
|
|
127
|
-
path
|
|
226
|
+
path?: string;
|
|
128
227
|
}
|
|
129
228
|
|
|
130
229
|
/** PivotTable layout cell kind. Mirrors `fm_pivot_cell_kind_t`. */
|
|
@@ -318,6 +417,8 @@ export interface PivotFilterSpec {
|
|
|
318
417
|
axis: PivotAxis;
|
|
319
418
|
fieldName: string;
|
|
320
419
|
type: PivotFilterType;
|
|
420
|
+
/** Data-field aggregate scored by value filters. Defaults to 0. */
|
|
421
|
+
dataFieldIndex?: number;
|
|
321
422
|
valueKind?: PivotFilterValueKind;
|
|
322
423
|
valueInt?: number;
|
|
323
424
|
valueDouble?: number;
|
|
@@ -327,6 +428,30 @@ export interface PivotFilterSpec {
|
|
|
327
428
|
valueHighDouble?: number;
|
|
328
429
|
}
|
|
329
430
|
|
|
431
|
+
/** Return type of `Workbook.pivotFilterAt(...)`: the stored filter plus a
|
|
432
|
+
* status envelope. Field names and semantics match `PivotFilterSpec`.
|
|
433
|
+
*
|
|
434
|
+
* The active-filter list is **session state**. An entry added through
|
|
435
|
+
* `pivotFilterAdd` affects evaluation only while the workbook handle
|
|
436
|
+
* lives and is not written by `save`. Conversely a `<filters>` block
|
|
437
|
+
* Excel wrote is preserved verbatim on save but does not appear here, so
|
|
438
|
+
* `pivotFilterCount` reports only what this session added. The filter
|
|
439
|
+
* surface that does persist is pivot field item visibility. */
|
|
440
|
+
export interface PivotFilterResult {
|
|
441
|
+
status: Status;
|
|
442
|
+
axis: number;
|
|
443
|
+
fieldName: string;
|
|
444
|
+
type: number;
|
|
445
|
+
dataFieldIndex: number;
|
|
446
|
+
valueKind: number;
|
|
447
|
+
valueInt: number;
|
|
448
|
+
valueDouble: number;
|
|
449
|
+
valueText: string;
|
|
450
|
+
valueHighKind: number;
|
|
451
|
+
valueHighInt: number;
|
|
452
|
+
valueHighDouble: number;
|
|
453
|
+
}
|
|
454
|
+
|
|
330
455
|
/** Conditional-format match kind. Mirrors `formulon::cf::CFMatchKind`. */
|
|
331
456
|
export enum CfMatchKind {
|
|
332
457
|
DifferentialFormat = 0,
|
|
@@ -335,6 +460,28 @@ export enum CfMatchKind {
|
|
|
335
460
|
IconSet = 3,
|
|
336
461
|
}
|
|
337
462
|
|
|
463
|
+
/** Excel cell-error ordinals. Mirrors `formulon::ErrorCode`; these are the
|
|
464
|
+
* values carried by `Value.errorCode` and accepted by `setError`. */
|
|
465
|
+
export enum ErrorCode {
|
|
466
|
+
Null = 0,
|
|
467
|
+
Div0 = 1,
|
|
468
|
+
Value = 2,
|
|
469
|
+
Ref = 3,
|
|
470
|
+
Name = 4,
|
|
471
|
+
Num = 5,
|
|
472
|
+
NA = 6,
|
|
473
|
+
GettingData = 7,
|
|
474
|
+
Spill = 8,
|
|
475
|
+
Calc = 9,
|
|
476
|
+
Field = 10,
|
|
477
|
+
Blocked = 11,
|
|
478
|
+
Connect = 12,
|
|
479
|
+
External = 13,
|
|
480
|
+
Busy = 14,
|
|
481
|
+
Python = 15,
|
|
482
|
+
Unknown = 16,
|
|
483
|
+
}
|
|
484
|
+
|
|
338
485
|
/**
|
|
339
486
|
* Workbook-level calc mode (`<calcPr calcMode>`).
|
|
340
487
|
*
|
|
@@ -353,6 +500,20 @@ export enum CalcMode {
|
|
|
353
500
|
|
|
354
501
|
export type ExcelProfileId = 'mac-365-ja_JP' | 'win-365-ja_JP';
|
|
355
502
|
|
|
503
|
+
/**
|
|
504
|
+
* A wall-clock reading in local civil fields, as read back from
|
|
505
|
+
* {@link Workbook.pinnedNow}. `month` is 1-12 and `day` is 1-31; the other
|
|
506
|
+
* fields follow the usual 24-hour ranges.
|
|
507
|
+
*/
|
|
508
|
+
export interface CivilTime {
|
|
509
|
+
year: number;
|
|
510
|
+
month: number;
|
|
511
|
+
day: number;
|
|
512
|
+
hour: number;
|
|
513
|
+
minute: number;
|
|
514
|
+
second: number;
|
|
515
|
+
}
|
|
516
|
+
|
|
356
517
|
/** RGBA colour. Channels are 0-255 (sRGB). */
|
|
357
518
|
export interface CfColor {
|
|
358
519
|
r: number;
|
|
@@ -393,33 +554,31 @@ export interface CfMatch {
|
|
|
393
554
|
iconIndex: number;
|
|
394
555
|
}
|
|
395
556
|
|
|
396
|
-
/** Iterable handle backing a `std::vector<CfMatch>` on the C++ side.
|
|
397
|
-
* Mirrors how embind surfaces `register_vector<T>`. */
|
|
398
|
-
export interface CfMatchVector {
|
|
399
|
-
size(): number;
|
|
400
|
-
get(index: number): CfMatch;
|
|
401
|
-
delete(): void;
|
|
402
|
-
}
|
|
403
|
-
|
|
404
557
|
/** One cell's CF result inside a viewport-range evaluation. */
|
|
405
558
|
export interface CfCellResult {
|
|
406
559
|
row: number;
|
|
407
560
|
col: number;
|
|
408
|
-
matches:
|
|
409
|
-
}
|
|
410
|
-
|
|
411
|
-
/** Iterable handle backing a `std::vector<CfCellResult>`. */
|
|
412
|
-
export interface CfCellVector {
|
|
413
|
-
size(): number;
|
|
414
|
-
get(index: number): CfCellResult;
|
|
415
|
-
delete(): void;
|
|
561
|
+
matches: ReadonlyArray<CfMatch>;
|
|
416
562
|
}
|
|
417
563
|
|
|
418
564
|
/** Return type of `Workbook.evaluateCfRange(...)`. `cells` is sparse:
|
|
419
565
|
* only cells that produced at least one match appear. */
|
|
420
566
|
export interface CfRangeResult {
|
|
421
567
|
status: Status;
|
|
422
|
-
cells:
|
|
568
|
+
cells: ReadonlyArray<CfCellResult>;
|
|
569
|
+
}
|
|
570
|
+
|
|
571
|
+
/** Resolved print geometry for one worksheet. All coordinates are 0-based. */
|
|
572
|
+
export interface PaginationResult {
|
|
573
|
+
status: Status;
|
|
574
|
+
/** The sheet's declared `_xlnm.Print_Area`. Empty when the sheet declares
|
|
575
|
+
* none -- it is not backfilled with the used range. Pagination itself
|
|
576
|
+
* still falls back to the used range in that case, so `pageCount` can be
|
|
577
|
+
* non-zero while this is empty. */
|
|
578
|
+
printArea: Array<{ firstRow: number; firstCol: number; lastRow: number; lastCol: number }>;
|
|
579
|
+
horizontalBreaks: number[];
|
|
580
|
+
verticalBreaks: number[];
|
|
581
|
+
pageCount: number;
|
|
423
582
|
}
|
|
424
583
|
|
|
425
584
|
/** Per-sheet view: zoom (10..400, default 100), frozen-pane row/col
|
|
@@ -505,19 +664,17 @@ export interface ColumnLayout {
|
|
|
505
664
|
/** Boolean stored as 0/1. */
|
|
506
665
|
hidden: number;
|
|
507
666
|
outlineLevel: number;
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
/**
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
get(index: number): ColumnLayout;
|
|
514
|
-
delete(): void;
|
|
667
|
+
/** Whether the width is logically explicit (raw presence or non-zero legacy width). */
|
|
668
|
+
hasWidth: number;
|
|
669
|
+
/** Whether the source / model carries an explicit style attribute. */
|
|
670
|
+
hasStyle: number;
|
|
671
|
+
styleXf: number;
|
|
515
672
|
}
|
|
516
673
|
|
|
517
674
|
/** Return type of `Workbook.getSheetColumns(sheet)`. */
|
|
518
675
|
export interface ColumnsResult {
|
|
519
676
|
status: Status;
|
|
520
|
-
columns:
|
|
677
|
+
columns: ReadonlyArray<ColumnLayout>;
|
|
521
678
|
}
|
|
522
679
|
|
|
523
680
|
/** Per-row layout override. */
|
|
@@ -527,19 +684,15 @@ export interface RowLayout {
|
|
|
527
684
|
/** Boolean stored as 0/1. */
|
|
528
685
|
hidden: number;
|
|
529
686
|
outlineLevel: number;
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
export interface RowLayoutVector {
|
|
534
|
-
size(): number;
|
|
535
|
-
get(index: number): RowLayout;
|
|
536
|
-
delete(): void;
|
|
687
|
+
/** Whether OOXML customFormat=1 makes the row style effective. */
|
|
688
|
+
hasStyle: number;
|
|
689
|
+
styleXf: number;
|
|
537
690
|
}
|
|
538
691
|
|
|
539
692
|
/** Return type of `Workbook.getSheetRowOverrides(sheet)`. */
|
|
540
693
|
export interface RowsResult {
|
|
541
694
|
status: Status;
|
|
542
|
-
rows:
|
|
695
|
+
rows: ReadonlyArray<RowLayout>;
|
|
543
696
|
}
|
|
544
697
|
|
|
545
698
|
/** Inclusive cell rectangle used by `addMerge` / `getMerges`. */
|
|
@@ -554,8 +707,13 @@ export interface MergeRange {
|
|
|
554
707
|
export interface HyperlinkEntry {
|
|
555
708
|
row: number;
|
|
556
709
|
col: number;
|
|
710
|
+
/** Inclusive bottom-right endpoint of the hyperlink rectangle. */
|
|
711
|
+
lastRow: number;
|
|
712
|
+
lastCol: number;
|
|
557
713
|
/** Absolute or relative target (URL, email, internal ref, …). */
|
|
558
714
|
target: string;
|
|
715
|
+
/** In-workbook destination (empty for an external target). */
|
|
716
|
+
location: string;
|
|
559
717
|
/** Display text override (empty when default). */
|
|
560
718
|
display: string;
|
|
561
719
|
/** Tooltip text (empty when none). */
|
|
@@ -568,6 +726,12 @@ export interface CommentEntry {
|
|
|
568
726
|
text: string;
|
|
569
727
|
}
|
|
570
728
|
|
|
729
|
+
/** Status-bearing comment lookup returned by `getCommentResult`. */
|
|
730
|
+
export interface CommentResult {
|
|
731
|
+
status: Status;
|
|
732
|
+
comment: CommentEntry | null;
|
|
733
|
+
}
|
|
734
|
+
|
|
571
735
|
/** Sheet-wide comment entry returned by `getComments(sheet)`. Extends
|
|
572
736
|
* `CommentEntry` with the anchor cell so comments on otherwise-empty
|
|
573
737
|
* cells can be discovered without already knowing their `(row, col)`. */
|
|
@@ -656,8 +820,9 @@ export interface CellNode {
|
|
|
656
820
|
* `ok` is `false` when no function matches `name`; the remaining
|
|
657
821
|
* fields are absent. When `ok` is `true`, `name` / `minArity` /
|
|
658
822
|
* `maxArity` are always populated; `signatureTemplate` and
|
|
659
|
-
* `description` are
|
|
660
|
-
*
|
|
823
|
+
* `description` are always `undefined` — the engine ships no
|
|
824
|
+
* human-readable function text and a host merges its own provider
|
|
825
|
+
* document over this result (`docs/function-metadata-schema.md`). */
|
|
661
826
|
export interface FunctionMetadataResult {
|
|
662
827
|
readonly ok: boolean;
|
|
663
828
|
readonly name?: string;
|
|
@@ -799,6 +964,19 @@ export interface ConditionalFormatEntry {
|
|
|
799
964
|
readonly showValue: boolean;
|
|
800
965
|
readonly minLengthPct: number;
|
|
801
966
|
readonly maxLengthPct: number;
|
|
967
|
+
/**
|
|
968
|
+
* `x14` extension payload. Present whenever the rule states the
|
|
969
|
+
* setting; a rule read back from a workbook always carries all six, so
|
|
970
|
+
* the object can be handed straight to `addConditionalFormat`.
|
|
971
|
+
*
|
|
972
|
+
* `axisPosition` is 0 = automatic, 1 = middle, 2 = none.
|
|
973
|
+
*/
|
|
974
|
+
readonly gradient?: boolean;
|
|
975
|
+
readonly axisPosition?: number;
|
|
976
|
+
readonly negativeFill?: CfColor;
|
|
977
|
+
readonly border?: CfColor;
|
|
978
|
+
readonly negativeBorder?: CfColor;
|
|
979
|
+
readonly axisColor?: CfColor;
|
|
802
980
|
};
|
|
803
981
|
/** Engaged for `iconSet` rules. */
|
|
804
982
|
readonly iconSet?: {
|
|
@@ -806,6 +984,9 @@ export interface ConditionalFormatEntry {
|
|
|
806
984
|
readonly thresholds: ReadonlyArray<CfValueObjectInput>;
|
|
807
985
|
readonly reverse: boolean;
|
|
808
986
|
readonly showValue: boolean;
|
|
987
|
+
/** Round-trip only: the `percent` attribute is preserved across load
|
|
988
|
+
* and save but never consulted during evaluation. Each threshold
|
|
989
|
+
* carries its own `type`, and that type is what interprets it. */
|
|
809
990
|
readonly percent: boolean;
|
|
810
991
|
};
|
|
811
992
|
}
|
|
@@ -846,6 +1027,18 @@ export interface ConditionalFormatInput {
|
|
|
846
1027
|
showValue?: boolean;
|
|
847
1028
|
minLengthPct?: number;
|
|
848
1029
|
maxLengthPct?: number;
|
|
1030
|
+
/**
|
|
1031
|
+
* `x14` extension payload. Omit a key to keep the model default:
|
|
1032
|
+
* gradient fill on, automatic axis, negative fill equal to `fill`, no
|
|
1033
|
+
* border, and a black axis. `axisPosition` is 0 = automatic,
|
|
1034
|
+
* 1 = middle, 2 = none.
|
|
1035
|
+
*/
|
|
1036
|
+
gradient?: boolean;
|
|
1037
|
+
axisPosition?: number;
|
|
1038
|
+
negativeFill?: CfColor;
|
|
1039
|
+
border?: CfColor;
|
|
1040
|
+
negativeBorder?: CfColor;
|
|
1041
|
+
axisColor?: CfColor;
|
|
849
1042
|
};
|
|
850
1043
|
/** Payload for type 4 (`iconSet`). `name` is `formulon::cf::IconSetName` ordinal. */
|
|
851
1044
|
iconSet?: {
|
|
@@ -853,6 +1046,9 @@ export interface ConditionalFormatInput {
|
|
|
853
1046
|
thresholds: ReadonlyArray<CfValueObjectInput>;
|
|
854
1047
|
reverse?: boolean;
|
|
855
1048
|
showValue?: boolean;
|
|
1049
|
+
/** Round-trip only: preserved across load and save but never
|
|
1050
|
+
* consulted during evaluation (each threshold's own `type` is
|
|
1051
|
+
* authoritative). */
|
|
856
1052
|
percent?: boolean;
|
|
857
1053
|
};
|
|
858
1054
|
}
|
|
@@ -873,6 +1069,53 @@ export interface CellXfResult {
|
|
|
873
1069
|
horizontalAlign: number;
|
|
874
1070
|
verticalAlign: number;
|
|
875
1071
|
wrapText: boolean;
|
|
1072
|
+
/** OOXML `justifyLastLine`; effective with distributed horizontal alignment. */
|
|
1073
|
+
justifyLastLine: boolean;
|
|
1074
|
+
/** Whether the source `<xf>` carried an `<alignment>` child. */
|
|
1075
|
+
hasAlignment: boolean;
|
|
1076
|
+
/** Whether `horizontal="..."` was explicitly present. */
|
|
1077
|
+
hasHorizontalAlign: boolean;
|
|
1078
|
+
/** Whether `vertical="..."` was explicitly present. */
|
|
1079
|
+
hasVerticalAlign: boolean;
|
|
1080
|
+
/** Whether `wrapText="..."` was explicitly present. */
|
|
1081
|
+
hasWrapText: boolean;
|
|
1082
|
+
/** Whether `justifyLastLine="..."` was explicitly present. */
|
|
1083
|
+
hasJustifyLastLine: boolean;
|
|
1084
|
+
/** OOXML `textRotation`; present only when the source attribute existed. */
|
|
1085
|
+
textRotation?: number;
|
|
1086
|
+
/** OOXML `indent`; present only when the source attribute existed. */
|
|
1087
|
+
indent?: number;
|
|
1088
|
+
/** OOXML signed `relativeIndent`; present only when the source attribute existed. */
|
|
1089
|
+
relativeIndent?: number;
|
|
1090
|
+
/** OOXML `shrinkToFit`; present only when the source attribute existed. */
|
|
1091
|
+
shrinkToFit?: boolean;
|
|
1092
|
+
/** OOXML `readingOrder`; present only when the source attribute existed. */
|
|
1093
|
+
readingOrder?: number;
|
|
1094
|
+
/** Index into `<cellStyleXfs>` of the named style this format inherits
|
|
1095
|
+
* from. Always 0 for a record read back from `getCellStyleXf`. */
|
|
1096
|
+
xfId?: number;
|
|
1097
|
+
}
|
|
1098
|
+
|
|
1099
|
+
/** How an OOXML `<color>` element expressed its value.
|
|
1100
|
+
* Mirrors `formulon::io::ColorSpec`.
|
|
1101
|
+
*
|
|
1102
|
+
* A record read from a workbook carries the original specification here.
|
|
1103
|
+
* When `kind` is non-zero, this selector is authoritative; the sibling
|
|
1104
|
+
* `*Argb` field is not an Excel-rendered value for theme/indexed/auto
|
|
1105
|
+
* selectors. It is literal RGB for `kind === 1`, or a compatibility
|
|
1106
|
+
* fallback otherwise. Leave `kind` at 0 on a record built from scratch and
|
|
1107
|
+
* the writer emits the sibling `*Argb` as `rgb`. */
|
|
1108
|
+
export interface ColorSpec {
|
|
1109
|
+
/** 0=none, 1=rgb, 2=theme, 3=indexed, 4=auto. */
|
|
1110
|
+
kind: number;
|
|
1111
|
+
/** AARRGGBB; meaningful when `kind` is 1. */
|
|
1112
|
+
rgb: number;
|
|
1113
|
+
/** Theme index; meaningful when `kind` is 2. */
|
|
1114
|
+
theme: number;
|
|
1115
|
+
/** Theme tint in -1..1; meaningful when `kind` is 2. */
|
|
1116
|
+
tint: number;
|
|
1117
|
+
/** Legacy palette index; meaningful when `kind` is 3. */
|
|
1118
|
+
indexed: number;
|
|
876
1119
|
}
|
|
877
1120
|
|
|
878
1121
|
/** Plain-data shape of a font record. Mirrors `formulon::io::FontRecord`. */
|
|
@@ -882,28 +1125,56 @@ export interface FontRecord {
|
|
|
882
1125
|
bold: boolean;
|
|
883
1126
|
italic: boolean;
|
|
884
1127
|
strike: boolean;
|
|
1128
|
+
/** Whether the source carried a `<b>` element at all. An absent element
|
|
1129
|
+
* on a differential font means "leave bold unchanged"; `hasBold` with
|
|
1130
|
+
* `bold: false` means "switch bold off". */
|
|
1131
|
+
hasBold: boolean;
|
|
1132
|
+
/** Whether the source carried an `<i>` element at all. */
|
|
1133
|
+
hasItalic: boolean;
|
|
1134
|
+
/** Whether the source carried a `<strike>` element at all. */
|
|
1135
|
+
hasStrike: boolean;
|
|
885
1136
|
/** 0=none, 1=single, 2=double, 3=singleAccounting, 4=doubleAccounting. */
|
|
886
1137
|
underline: number;
|
|
887
|
-
/**
|
|
1138
|
+
/** 0=baseline, 1=superscript, 2=subscript. */
|
|
1139
|
+
vertAlign: number;
|
|
1140
|
+
/** Whether the source carried a `<family>` element. */
|
|
1141
|
+
hasFamily: boolean;
|
|
1142
|
+
/** OOXML font-family class (0..5). */
|
|
1143
|
+
family: number;
|
|
1144
|
+
/** Whether the source carried a `<charset>` element. */
|
|
1145
|
+
hasCharset: boolean;
|
|
1146
|
+
/** OOXML charset codepage id (e.g. 128 = Shift_JIS). */
|
|
1147
|
+
charset: number;
|
|
1148
|
+
/** AARRGGBB literal RGB or compatibility fallback; not a resolved
|
|
1149
|
+
* theme/indexed/auto render colour. */
|
|
888
1150
|
colorArgb: number;
|
|
1151
|
+
/** Original `<color>` specification, preserved for round-tripping. */
|
|
1152
|
+
color: ColorSpec;
|
|
889
1153
|
}
|
|
890
1154
|
|
|
891
1155
|
/** Plain-data shape of a fill record. Mirrors `formulon::io::FillRecord`. */
|
|
892
1156
|
export interface FillRecord {
|
|
893
1157
|
/** OOXML pattern ordinal: 0=none, 1=solid, 2..18=standard pattern set. */
|
|
894
1158
|
pattern: number;
|
|
895
|
-
/** Foreground
|
|
1159
|
+
/** Foreground literal RGB or compatibility fallback. */
|
|
896
1160
|
fgArgb: number;
|
|
897
|
-
/** Background
|
|
1161
|
+
/** Background literal RGB or compatibility fallback. */
|
|
898
1162
|
bgArgb: number;
|
|
1163
|
+
/** Original `<fgColor>` specification, preserved for round-tripping. */
|
|
1164
|
+
fg: ColorSpec;
|
|
1165
|
+
/** Original `<bgColor>` specification, preserved for round-tripping. */
|
|
1166
|
+
bg: ColorSpec;
|
|
899
1167
|
}
|
|
900
1168
|
|
|
901
1169
|
/** One side of a `BorderRecord`. */
|
|
902
1170
|
export interface BorderSide {
|
|
903
1171
|
/** OOXML border-style ordinal: 0=none, 1=thin, ..., 13=slantDashDot. */
|
|
904
1172
|
style: number;
|
|
905
|
-
/** AARRGGBB
|
|
1173
|
+
/** AARRGGBB literal RGB or compatibility fallback; not a resolved
|
|
1174
|
+
* theme/indexed/auto render colour. */
|
|
906
1175
|
colorArgb: number;
|
|
1176
|
+
/** Original `<color>` specification, preserved for round-tripping. */
|
|
1177
|
+
color: ColorSpec;
|
|
907
1178
|
}
|
|
908
1179
|
|
|
909
1180
|
/** Plain-data shape of a border record. Mirrors `formulon::io::BorderRecord`. */
|
|
@@ -928,6 +1199,32 @@ export interface CellXf {
|
|
|
928
1199
|
/** 0=top, 1=center, 2=bottom, 3=justify, 4=distributed. */
|
|
929
1200
|
verticalAlign: number;
|
|
930
1201
|
wrapText: boolean;
|
|
1202
|
+
/** OOXML `justifyLastLine`; effective with distributed alignment. Defaults to false. */
|
|
1203
|
+
justifyLastLine?: boolean;
|
|
1204
|
+
/** Whether to preserve an explicit alignment child. Omit to infer from supplied alignment fields. */
|
|
1205
|
+
hasAlignment?: boolean;
|
|
1206
|
+
/** Whether `horizontalAlign` was explicitly supplied; defaults to inference. */
|
|
1207
|
+
hasHorizontalAlign?: boolean;
|
|
1208
|
+
/** Whether `verticalAlign` was explicitly supplied; defaults to inference. */
|
|
1209
|
+
hasVerticalAlign?: boolean;
|
|
1210
|
+
/** Whether `wrapText` was explicitly supplied; defaults to inference. */
|
|
1211
|
+
hasWrapText?: boolean;
|
|
1212
|
+
/** Whether `justifyLastLine` was explicitly supplied; defaults to inference. */
|
|
1213
|
+
hasJustifyLastLine?: boolean;
|
|
1214
|
+
/** OOXML `textRotation` (0..180 or 255). Omitted when absent. */
|
|
1215
|
+
textRotation?: number;
|
|
1216
|
+
/** OOXML `indent` (0..255). Omitted when absent. */
|
|
1217
|
+
indent?: number;
|
|
1218
|
+
/** OOXML signed `relativeIndent`. Omitted when absent. */
|
|
1219
|
+
relativeIndent?: number;
|
|
1220
|
+
/** OOXML `shrinkToFit`; omitted when absent so explicit false is retained. */
|
|
1221
|
+
shrinkToFit?: boolean;
|
|
1222
|
+
/** OOXML `readingOrder` (0=context, 1=LTR, 2=RTL). Omitted when absent. */
|
|
1223
|
+
readingOrder?: number;
|
|
1224
|
+
/** Index of the named style in `<cellStyleXfs>` this format inherits from.
|
|
1225
|
+
* Only meaningful for `addXf`; must name an entry created by
|
|
1226
|
+
* `addCellStyleXf`. Defaults to 0. */
|
|
1227
|
+
xfId?: number;
|
|
931
1228
|
}
|
|
932
1229
|
|
|
933
1230
|
/** Return type of `Workbook.getFont(fontIndex)`. */
|
|
@@ -962,6 +1259,10 @@ export interface DxfRecord {
|
|
|
962
1259
|
numFmtId: number;
|
|
963
1260
|
formatCode: string;
|
|
964
1261
|
};
|
|
1262
|
+
/** Serialized OOXML `<alignment .../>` child; lexical formatting may normalize on load. */
|
|
1263
|
+
alignmentXml?: string;
|
|
1264
|
+
/** Serialized OOXML `<protection .../>` child; lexical formatting may normalize on load. */
|
|
1265
|
+
protectionXml?: string;
|
|
965
1266
|
}
|
|
966
1267
|
|
|
967
1268
|
export interface DxfResult extends DxfRecord {
|
|
@@ -979,9 +1280,20 @@ export interface LambdaTextResult {
|
|
|
979
1280
|
text: string;
|
|
980
1281
|
}
|
|
981
1282
|
|
|
1283
|
+
/** Minimum severity for the engine's structured log stream. Mirrors
|
|
1284
|
+
* `fm_log_level_t`. `Off` discards every record and is the default: an
|
|
1285
|
+
* embedded library must not write to the host's stderr unless asked. */
|
|
1286
|
+
export enum LogLevel {
|
|
1287
|
+
Debug = 0,
|
|
1288
|
+
Info = 1,
|
|
1289
|
+
Warn = 2,
|
|
1290
|
+
Error = 3,
|
|
1291
|
+
Off = 4,
|
|
1292
|
+
}
|
|
1293
|
+
|
|
982
1294
|
/** External-link kinds. Mirrors
|
|
983
1295
|
* `formulon::io::ExternalLinkRecord::Kind`. */
|
|
984
|
-
export
|
|
1296
|
+
export enum ExternalLinkKind {
|
|
985
1297
|
Unknown = 0,
|
|
986
1298
|
ExternalBook = 1,
|
|
987
1299
|
Ole = 2,
|
|
@@ -1040,8 +1352,9 @@ export interface AddStyleResult {
|
|
|
1040
1352
|
index: number;
|
|
1041
1353
|
}
|
|
1042
1354
|
|
|
1043
|
-
/** Return type of `Workbook.addNumFmt(formatCode)`. The id
|
|
1044
|
-
*
|
|
1355
|
+
/** Return type of `Workbook.addNumFmt(formatCode)`. The id may reuse any
|
|
1356
|
+
* existing effective mapping (built-in or custom, including a custom record
|
|
1357
|
+
* overriding a built-in slot), or be a freshly-assigned custom id (`>= 164`). */
|
|
1045
1358
|
export interface AddNumFmtResult {
|
|
1046
1359
|
status: Status;
|
|
1047
1360
|
numFmtId: number;
|
|
@@ -1063,6 +1376,13 @@ export interface PartialRecalcResult {
|
|
|
1063
1376
|
recomputed: number;
|
|
1064
1377
|
}
|
|
1065
1378
|
|
|
1379
|
+
/** Result of `Workbook.getSheetAutoFilterXml`. The empty `xml` string means
|
|
1380
|
+
* that the sheet has no AutoFilter definition. */
|
|
1381
|
+
export interface SheetAutoFilterXmlResult {
|
|
1382
|
+
status: Status;
|
|
1383
|
+
xml: string;
|
|
1384
|
+
}
|
|
1385
|
+
|
|
1066
1386
|
/** Iterative-solver progress callback. Receives the current
|
|
1067
1387
|
* iteration number, the maximum residual seen, and the configured
|
|
1068
1388
|
* iteration cap. Returning `false` (or any falsy value) aborts the
|
|
@@ -1082,7 +1402,11 @@ export interface Workbook {
|
|
|
1082
1402
|
|
|
1083
1403
|
save(): SaveResult;
|
|
1084
1404
|
/** Serialises using an explicit container `format` (see `WorkbookFormat`). */
|
|
1085
|
-
|
|
1405
|
+
saveAs(format: WorkbookFormat | number): SaveResult;
|
|
1406
|
+
/** Serialises using an explicit format and reports loss/defer counters. */
|
|
1407
|
+
saveWithDiagnostics(format: WorkbookFormat | number): SaveDiagnosticsResult;
|
|
1408
|
+
/** Returns the loss counters captured when this handle was loaded. */
|
|
1409
|
+
readDiagnostics(): ReadDiagnosticsResult;
|
|
1086
1410
|
addSheet(name: string): Status;
|
|
1087
1411
|
/** Removes the sheet at `index`. */
|
|
1088
1412
|
removeSheet(index: number): Status;
|
|
@@ -1098,6 +1422,8 @@ export interface Workbook {
|
|
|
1098
1422
|
/** Stores a static Excel error literal; `errorCode` is an ErrorCode ordinal. */
|
|
1099
1423
|
setError(sheet: number, row: number, col: number, errorCode: number): Status;
|
|
1100
1424
|
setText(sheet: number, row: number, col: number, text: string): Status;
|
|
1425
|
+
/** Stores (or, when empty, clears) the cell's OOXML phonetic guide (`<rPh>`). */
|
|
1426
|
+
setCellPhonetic(sheet: number, row: number, col: number, phonetic: string): Status;
|
|
1101
1427
|
setBlank(sheet: number, row: number, col: number): Status;
|
|
1102
1428
|
setFormula(sheet: number, row: number, col: number, formula: string): Status;
|
|
1103
1429
|
|
|
@@ -1140,8 +1466,23 @@ export interface Workbook {
|
|
|
1140
1466
|
* formula text. Returns `kInvalidArgument` when the cell is absent
|
|
1141
1467
|
* or its cached value is not a lambda. */
|
|
1142
1468
|
getLambdaText(sheet: number, row: number, col: number): LambdaTextResult;
|
|
1469
|
+
/** Returns the cell's OOXML phonetic guide (`<rPh>`), or an empty string. */
|
|
1470
|
+
getCellPhonetic(sheet: number, row: number, col: number): StringResult;
|
|
1143
1471
|
|
|
1472
|
+
/** Recalculates all dirty cells serially on the caller thread. */
|
|
1144
1473
|
recalc(): Status;
|
|
1474
|
+
/**
|
|
1475
|
+
* Recalculates all dirty cells using the parallel SCC scheduler and returns
|
|
1476
|
+
* per-call telemetry. This call is synchronous: it returns after all
|
|
1477
|
+
* workers have joined. `threadCount` must be a finite integer: 0 selects
|
|
1478
|
+
* automatic detection (capped at 8), 1 keeps evaluation on the caller and
|
|
1479
|
+
* starts no workers, and 2..8 set the worker upper bound. Missing,
|
|
1480
|
+
* fractional, non-finite, negative, or above-8 values fail with
|
|
1481
|
+
* `kInvalidArgument`.
|
|
1482
|
+
* The `uint64_t` counters in `stats` are JavaScript numbers and are exact
|
|
1483
|
+
* through `Number.MAX_SAFE_INTEGER` (2^53 - 1).
|
|
1484
|
+
*/
|
|
1485
|
+
recalcParallel(threadCount: number): ParallelRecalcResult;
|
|
1145
1486
|
/** Recalculates only cells touched by the supplied viewport. */
|
|
1146
1487
|
partialRecalc(viewport: RecalcViewport): PartialRecalcResult;
|
|
1147
1488
|
|
|
@@ -1162,6 +1503,34 @@ export interface Workbook {
|
|
|
1162
1503
|
calcMode(): CalcMode;
|
|
1163
1504
|
setCalcMode(mode: CalcMode): Status;
|
|
1164
1505
|
|
|
1506
|
+
/**
|
|
1507
|
+
* The workbook's pinned wall-clock reading, or `null` when it follows the
|
|
1508
|
+
* host clock (the default).
|
|
1509
|
+
*
|
|
1510
|
+
* Pinning gives `NOW()`, `TODAY()` and the pivot relative-period filters
|
|
1511
|
+
* ("this month", "year to date", ...) one instant to agree on. Without a
|
|
1512
|
+
* pin each reads the clock independently, which makes a recalc internally
|
|
1513
|
+
* inconsistent across a midnight boundary and makes any such result
|
|
1514
|
+
* untestable.
|
|
1515
|
+
*
|
|
1516
|
+
* Local civil fields are carried rather than a timestamp so the reading has
|
|
1517
|
+
* no residual timezone interpretation: the same values reproduce the same
|
|
1518
|
+
* results in any zone. This is model state, not file state — `save()` does
|
|
1519
|
+
* not record it and a reloaded workbook comes back unpinned.
|
|
1520
|
+
*
|
|
1521
|
+
* Cached formula values are not recomputed by `setPinnedNow`; drive
|
|
1522
|
+
* `recalc()` to see the pin take effect on existing cells.
|
|
1523
|
+
*
|
|
1524
|
+
* `setPinnedNow` returns `kInvalidArgument` unless `year` is in
|
|
1525
|
+
* `[1900, 9999]`, `month` in `[1, 12]`, `day` within that month's real
|
|
1526
|
+
* length, `hour` in `[0, 23]`, and `minute` / `second` in `[0, 59]`. The
|
|
1527
|
+
* pin is a calendar instant, not a normalising constructor: a month of 13
|
|
1528
|
+
* is rejected rather than rolled into the next year.
|
|
1529
|
+
*/
|
|
1530
|
+
pinnedNow(): CivilTime | null;
|
|
1531
|
+
setPinnedNow(year: number, month: number, day: number, hour: number, minute: number, second: number): Status;
|
|
1532
|
+
clearPinnedNow(): Status;
|
|
1533
|
+
|
|
1165
1534
|
/**
|
|
1166
1535
|
* Full formula-behaviour profile id. Defaults to `win-365-ja_JP`.
|
|
1167
1536
|
*/
|
|
@@ -1193,6 +1562,17 @@ export interface Workbook {
|
|
|
1193
1562
|
|
|
1194
1563
|
tableCount(): number;
|
|
1195
1564
|
tableAt(idx: number): TableEntry;
|
|
1565
|
+
createTable(input: TableInput): AddStyleResult;
|
|
1566
|
+
/** Partially updates a table. Omitted fields preserve their current
|
|
1567
|
+
* values. A supplied `ref` must keep the table's existing column count;
|
|
1568
|
+
* an empty `styleName` clears the style. */
|
|
1569
|
+
updateTable(idx: number, input: TableUpdateInput): Status;
|
|
1570
|
+
removeTable(idx: number): Status;
|
|
1571
|
+
|
|
1572
|
+
/** Reads the complete worksheet-level `<autoFilter>` XML fragment. */
|
|
1573
|
+
getSheetAutoFilterXml(sheet: number): SheetAutoFilterXmlResult;
|
|
1574
|
+
/** Replaces the worksheet-level `<autoFilter>` XML fragment; empty clears it. */
|
|
1575
|
+
setSheetAutoFilterXml(sheet: number, xml: string): Status;
|
|
1196
1576
|
|
|
1197
1577
|
passthroughCount(): number;
|
|
1198
1578
|
passthroughAt(idx: number): PassthroughEntry;
|
|
@@ -1349,18 +1729,25 @@ export interface Workbook {
|
|
|
1349
1729
|
/** Replaces the data-field entry at `dataFieldIdx` in place. */
|
|
1350
1730
|
pivotDataFieldSet(sheet: number, pivotIdx: number, dataFieldIdx: number, spec: PivotDataFieldSpec): Status;
|
|
1351
1731
|
|
|
1352
|
-
/** Number of active (slicer-applied) filters on the pivot.
|
|
1732
|
+
/** Number of active (slicer-applied) filters on the pivot. Counts only
|
|
1733
|
+
* the entries this session added -- see {@link PivotFilterResult}. */
|
|
1353
1734
|
pivotFilterCount(sheet: number, pivotIdx: number): number;
|
|
1354
|
-
/** Appends an active filter.
|
|
1735
|
+
/** Appends an active filter. The entry is session state and is not
|
|
1736
|
+
* written by `save`; see {@link PivotFilterResult}. */
|
|
1355
1737
|
pivotFilterAdd(sheet: number, pivotIdx: number, spec: PivotFilterSpec): Status;
|
|
1738
|
+
/** Reads the active filter at `filterIdx`. The list is session state:
|
|
1739
|
+
* see {@link PivotFilterResult}. */
|
|
1740
|
+
pivotFilterAt(sheet: number, pivotIdx: number, filterIdx: number): PivotFilterResult;
|
|
1356
1741
|
/** Drops every active filter from the pivot. */
|
|
1357
1742
|
pivotFilterClear(sheet: number, pivotIdx: number): Status;
|
|
1358
1743
|
/** Removes the active filter at `filterIdx`. */
|
|
1359
1744
|
pivotFilterRemoveAt(sheet: number, pivotIdx: number, filterIdx: number): Status;
|
|
1360
1745
|
|
|
1361
1746
|
/** Evaluates every CF block on `sheet` against the inclusive range
|
|
1362
|
-
* `[(firstRow, firstCol), (lastRow, lastCol)]`.
|
|
1363
|
-
*
|
|
1747
|
+
* `[(firstRow, firstCol), (lastRow, lastCol)]`. `todaySerial` pins the
|
|
1748
|
+
* date basis for `TimePeriod` rules; pass `NaN` to disable them (no
|
|
1749
|
+
* `TimePeriod` rule then matches). `0` does *not* disable them -- it is
|
|
1750
|
+
* the valid serial for 1899-12-30. */
|
|
1364
1751
|
evaluateCfRange(
|
|
1365
1752
|
sheet: number,
|
|
1366
1753
|
firstRow: number,
|
|
@@ -1370,6 +1757,9 @@ export interface Workbook {
|
|
|
1370
1757
|
todaySerial: number,
|
|
1371
1758
|
): CfRangeResult;
|
|
1372
1759
|
|
|
1760
|
+
/** Computes print-area page breaks and physical page count for `sheet`. */
|
|
1761
|
+
paginate(sheet: number): PaginationResult;
|
|
1762
|
+
|
|
1373
1763
|
/** Reads the full per-sheet view (zoom, freeze, tab-hidden, and the
|
|
1374
1764
|
* display / orientation flags). */
|
|
1375
1765
|
getSheetView(sheet: number): SheetViewResult;
|
|
@@ -1429,11 +1819,11 @@ export interface Workbook {
|
|
|
1429
1819
|
setCellXfIndex(sheet: number, row: number, col: number, xfIndex: number): Status;
|
|
1430
1820
|
/** Returns the resolved XF record at `xfIndex`. */
|
|
1431
1821
|
getCellXf(xfIndex: number): CellXfResult;
|
|
1432
|
-
/** Returns the
|
|
1822
|
+
/** Returns the font record at `fontIndex`, including its ColorSpec selector. */
|
|
1433
1823
|
getFont(fontIndex: number): FontResult;
|
|
1434
|
-
/** Returns the
|
|
1824
|
+
/** Returns the fill record at `fillIndex`, including its ColorSpec selectors. */
|
|
1435
1825
|
getFill(fillIndex: number): FillResult;
|
|
1436
|
-
/** Returns the
|
|
1826
|
+
/** Returns the border record at `borderIndex`, including its ColorSpec selectors. */
|
|
1437
1827
|
getBorder(borderIndex: number): BorderResult;
|
|
1438
1828
|
/** Returns the format string registered for `numFmtId`. */
|
|
1439
1829
|
getNumFmt(numFmtId: number): NumFmtResult;
|
|
@@ -1447,9 +1837,13 @@ export interface Workbook {
|
|
|
1447
1837
|
addFill(record: FillRecord): AddStyleResult;
|
|
1448
1838
|
/** Adds a border (deduplicating against existing entries). */
|
|
1449
1839
|
addBorder(record: BorderRecord): AddStyleResult;
|
|
1450
|
-
/** Adds a number-format code.
|
|
1451
|
-
*
|
|
1452
|
-
*
|
|
1840
|
+
/** Adds a number-format code. An existing effective mapping is reused,
|
|
1841
|
+
* including an existing custom record; a built-in id is reused without
|
|
1842
|
+
* modifying the table only when its current effective mapping matches the
|
|
1843
|
+
* code. Otherwise custom codes are appended at
|
|
1844
|
+
* `max(existing_custom_id, 163) + 1`. Effective mappings use the first
|
|
1845
|
+
* valid custom record for an id in document order, then a non-empty
|
|
1846
|
+
* built-in code. */
|
|
1453
1847
|
addNumFmt(formatCode: string): AddNumFmtResult;
|
|
1454
1848
|
/** Adds an `<xf>` record (deduplicating against existing entries).
|
|
1455
1849
|
* Out-of-range font/fill/border indices or unregistered `numFmtId`
|
|
@@ -1484,12 +1878,20 @@ export interface Workbook {
|
|
|
1484
1878
|
/** Returns the named-style xf record at `index`. Output shape mirrors
|
|
1485
1879
|
* `getCellXf`. */
|
|
1486
1880
|
getCellStyleXf(index: number): CellXfResult;
|
|
1881
|
+
/** Appends (deduplicating) a named-style xf and returns its
|
|
1882
|
+
* `<cellStyleXfs>` index, which is what `setCellStyle` and
|
|
1883
|
+
* `CellXf.xfId` reference. */
|
|
1884
|
+
addCellStyleXf(record: CellXf): AddStyleResult;
|
|
1885
|
+
/** Adds or replaces the `<cellStyle>` entry named `name`. `builtinId` is
|
|
1886
|
+
* an OOXML ordinal `0..47`, or `0xFFFFFFFF` for a custom style; it is
|
|
1887
|
+
* required because the binding takes a fixed argument count. */
|
|
1888
|
+
setCellStyle(name: string, xfId: number, builtinId: number): Status;
|
|
1487
1889
|
|
|
1488
1890
|
/** Returns every external-link record carried by the workbook in
|
|
1489
1891
|
* `<externalReferences>` document order. Empty for fresh workbooks
|
|
1490
1892
|
* and any package whose source archive had no `<externalReferences>`
|
|
1491
1893
|
* block. */
|
|
1492
|
-
getExternalLinks():
|
|
1894
|
+
getExternalLinks(): ListResult<ExternalLinkRecord>;
|
|
1493
1895
|
|
|
1494
1896
|
/** Adds a merge range to `sheet`. */
|
|
1495
1897
|
addMerge(sheet: number, range: MergeRange): Status;
|
|
@@ -1500,21 +1902,42 @@ export interface Workbook {
|
|
|
1500
1902
|
/** Drops every merge on `sheet`. */
|
|
1501
1903
|
clearMerges(sheet: number): Status;
|
|
1502
1904
|
/** Returns every merge range on `sheet` as a JS array. */
|
|
1503
|
-
getMerges(sheet: number):
|
|
1905
|
+
getMerges(sheet: number): ListResult<MergeRange>;
|
|
1504
1906
|
|
|
1505
1907
|
/** Returns the cell comment at `(sheet, row, col)`, or `null` when absent. */
|
|
1506
1908
|
getComment(sheet: number, row: number, col: number): CommentEntry | null;
|
|
1909
|
+
/** Returns a comment lookup result that distinguishes absence from an invalid sheet or handle. */
|
|
1910
|
+
getCommentResult(sheet: number, row: number, col: number): CommentResult;
|
|
1507
1911
|
/** Returns every comment on `sheet`, including comments anchored on
|
|
1508
1912
|
* cells that carry no value. */
|
|
1509
|
-
getComments(sheet: number):
|
|
1913
|
+
getComments(sheet: number): ListResult<SheetCommentEntry>;
|
|
1510
1914
|
/** Sets / replaces the cell comment. Pass an empty `text` to remove. */
|
|
1511
1915
|
setComment(sheet: number, row: number, col: number, author: string, text: string): Status;
|
|
1512
1916
|
|
|
1513
|
-
/** Appends a hyperlink to `sheet`.
|
|
1514
|
-
*
|
|
1515
|
-
|
|
1516
|
-
|
|
1517
|
-
|
|
1917
|
+
/** Appends a hyperlink to `sheet`. For an in-workbook link, pass an empty
|
|
1918
|
+
* `target` and its A1 destination as `location`. */
|
|
1919
|
+
addHyperlink(
|
|
1920
|
+
sheet: number,
|
|
1921
|
+
row: number,
|
|
1922
|
+
col: number,
|
|
1923
|
+
target: string,
|
|
1924
|
+
display: string,
|
|
1925
|
+
tooltip: string,
|
|
1926
|
+
location: string,
|
|
1927
|
+
): Status;
|
|
1928
|
+
/** Appends a hyperlink covering the inclusive rectangle from `(row, col)`
|
|
1929
|
+
* through `(lastRow, lastCol)`. */
|
|
1930
|
+
addHyperlinkRange(
|
|
1931
|
+
sheet: number,
|
|
1932
|
+
row: number,
|
|
1933
|
+
col: number,
|
|
1934
|
+
lastRow: number,
|
|
1935
|
+
lastCol: number,
|
|
1936
|
+
target: string,
|
|
1937
|
+
display: string,
|
|
1938
|
+
tooltip: string,
|
|
1939
|
+
location: string,
|
|
1940
|
+
): Status;
|
|
1518
1941
|
/** Removes every hyperlink anchored at `(row, col)`. No-op when none match. */
|
|
1519
1942
|
removeHyperlink(sheet: number, row: number, col: number): Status;
|
|
1520
1943
|
/** Removes the hyperlink at `index`. Returns kInvalidArgument if `index` is out of range. */
|
|
@@ -1522,13 +1945,13 @@ export interface Workbook {
|
|
|
1522
1945
|
/** Drops every hyperlink on `sheet`. */
|
|
1523
1946
|
clearHyperlinks(sheet: number): Status;
|
|
1524
1947
|
/** Returns every hyperlink on `sheet` as a JS array. */
|
|
1525
|
-
getHyperlinks(sheet: number):
|
|
1948
|
+
getHyperlinks(sheet: number): ListResult<HyperlinkEntry>;
|
|
1526
1949
|
|
|
1527
1950
|
/** Returns every data-validation rule on `sheet` in storage order.
|
|
1528
1951
|
* Each rule's `ranges` mirrors the OOXML `<dataValidation sqref=...>`
|
|
1529
1952
|
* cell-range list; the rule itself surfaces its raw OOXML payload
|
|
1530
1953
|
* (the engine does not yet evaluate validation rules). */
|
|
1531
|
-
getValidations(sheet: number):
|
|
1954
|
+
getValidations(sheet: number): ListResult<DataValidationEntry>;
|
|
1532
1955
|
/** Appends a data-validation rule to `sheet`. */
|
|
1533
1956
|
addValidation(sheet: number, validation: DataValidationInput): Status;
|
|
1534
1957
|
/** Removes the validation rule at `index`. Returns `kInvalidArgument`
|
|
@@ -1540,7 +1963,7 @@ export interface Workbook {
|
|
|
1540
1963
|
/** Returns every CF rule on `sheet` in flattened priority order. The
|
|
1541
1964
|
* returned entries borrow rule ids from the engine's storage; treat
|
|
1542
1965
|
* them as immutable view objects. */
|
|
1543
|
-
getConditionalFormats(sheet: number):
|
|
1966
|
+
getConditionalFormats(sheet: number): ListResult<ConditionalFormatEntry>;
|
|
1544
1967
|
/** Appends a new single-rule `<conditionalFormatting>` block to
|
|
1545
1968
|
* `sheet`, including visual rules when their payload object is supplied.
|
|
1546
1969
|
* `index` is the new rule's position in the sheet's flattened CF rule
|
|
@@ -1565,24 +1988,25 @@ export interface Workbook {
|
|
|
1565
1988
|
|
|
1566
1989
|
/** Returns metadata for the function `name` (case-insensitive). When
|
|
1567
1990
|
* the function is unknown, returns `{ok: false}`. `locale` selects
|
|
1568
|
-
* the catalog locale (`0` = `en-US`, `1` = `ja-JP`)
|
|
1569
|
-
*
|
|
1570
|
-
*
|
|
1991
|
+
* the catalog locale (`0` = `en-US`, `1` = `ja-JP`) and is validated,
|
|
1992
|
+
* but does not change the result: the description / signature fields
|
|
1993
|
+
* are always `undefined` (see {@link FunctionMetadataResult}). */
|
|
1571
1994
|
functionMetadata(name: string, locale: number): FunctionMetadataResult;
|
|
1572
1995
|
/** Returns every registered function's canonical name in ascending
|
|
1573
1996
|
* sort order. */
|
|
1574
1997
|
functionNames(): ReadonlyArray<string>;
|
|
1575
1998
|
|
|
1576
1999
|
/** Returns the localized display name for the canonical function
|
|
1577
|
-
* `canonicalName` in `locale`.
|
|
1578
|
-
*
|
|
1579
|
-
*
|
|
1580
|
-
* name does not match a registered
|
|
2000
|
+
* `canonicalName` in `locale`. No alias table exists in any locale,
|
|
2001
|
+
* so this always returns the canonical name unchanged; localized
|
|
2002
|
+
* display names belong to the host's provider document. Returns the
|
|
2003
|
+
* empty string when the canonical name does not match a registered
|
|
2004
|
+
* function. */
|
|
1581
2005
|
localizeFunctionName(canonicalName: string, locale: number): string;
|
|
1582
2006
|
/** Inverse of `localizeFunctionName`: returns the canonical English
|
|
1583
|
-
* name for the localized function `localizedName`.
|
|
1584
|
-
* case-insensitive canonical-name
|
|
1585
|
-
*
|
|
2007
|
+
* name for the localized function `localizedName`. With no alias
|
|
2008
|
+
* table this is a case-insensitive canonical-name match, in every
|
|
2009
|
+
* locale. Returns the empty string when no function matches. */
|
|
1586
2010
|
canonicalizeFunctionName(localizedName: string, locale: number): string;
|
|
1587
2011
|
|
|
1588
2012
|
/** Returns dynamic-array spill info for `(sheet, row, col)`.
|
|
@@ -1610,8 +2034,12 @@ export interface WorkbookCtor {
|
|
|
1610
2034
|
export interface FormulonModule {
|
|
1611
2035
|
Workbook: WorkbookCtor;
|
|
1612
2036
|
|
|
1613
|
-
/** Convenience: evaluates
|
|
1614
|
-
*
|
|
2037
|
+
/** Convenience: evaluates `formula` read-only against a fresh
|
|
2038
|
+
* single-sheet workbook, anchored at `Sheet1!A1`. Nothing is written
|
|
2039
|
+
* and no recalc runs, so an anchor-referencing formula such as `=A1`
|
|
2040
|
+
* or `=COUNTA(A1)` reads the blank anchor rather than becoming a
|
|
2041
|
+
* self-reference. An array result is reduced to its top-left element;
|
|
2042
|
+
* use `Workbook.evaluateFormulaArray` for the whole grid. */
|
|
1615
2043
|
evalFormula(formula: string): EvalResult;
|
|
1616
2044
|
|
|
1617
2045
|
/** Library version string (UTF-8). */
|
|
@@ -1623,11 +2051,31 @@ export interface FormulonModule {
|
|
|
1623
2051
|
/** Static description of `status` (e.g. `"kOk"`). */
|
|
1624
2052
|
statusString(status: number): string;
|
|
1625
2053
|
|
|
2054
|
+
/** Excel display literal for a cell error code (e.g. `"#DIV/0!"`). */
|
|
2055
|
+
errorDisplayName(errorCode: number): string;
|
|
2056
|
+
|
|
1626
2057
|
/** Most-recent thread-local error message. */
|
|
1627
2058
|
lastErrorMessage(): string;
|
|
1628
2059
|
|
|
1629
2060
|
/** Most-recent thread-local error context. */
|
|
1630
2061
|
lastErrorContext(): string;
|
|
2062
|
+
|
|
2063
|
+
/** Sets the engine's minimum structured-log severity (a `LogLevel`
|
|
2064
|
+
* ordinal). This is **process-wide** state, not per `Workbook`. The
|
|
2065
|
+
* default is `LogLevel.Off`, under which the engine writes nothing to
|
|
2066
|
+
* stderr and invokes no sink. */
|
|
2067
|
+
setLogMinLevel(level: number): Status;
|
|
2068
|
+
|
|
2069
|
+
/** Routes structured-log records to `sink`, or restores the (silent at
|
|
2070
|
+
* the default threshold) stderr fallback when `sink` is `null`.
|
|
2071
|
+
* **Process-wide** state, not per `Workbook`.
|
|
2072
|
+
*
|
|
2073
|
+
* `sink` receives one complete JSON record as raw bytes -- the C ABI
|
|
2074
|
+
* hands the binding a length-delimited range, never a NUL-terminated
|
|
2075
|
+
* string. The view is only valid for the duration of the call; copy it
|
|
2076
|
+
* (`new Uint8Array(record)`) or decode it (`new TextDecoder().decode(
|
|
2077
|
+
* record)`) before returning. */
|
|
2078
|
+
setLogSink(sink: ((record: Uint8Array) => void) | null): Status;
|
|
1631
2079
|
}
|
|
1632
2080
|
|
|
1633
2081
|
/** Optional Emscripten module-init overrides. Pass to the factory to
|