@libraz/formulon 0.12.0 → 0.14.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.
@@ -22,7 +22,8 @@ export enum ValueKind {
22
22
  Lambda = 7,
23
23
  }
24
24
 
25
- /** Result envelope returned by every fallible binding call. */
25
+ /** Status carried by binding result envelopes. Argument validation may
26
+ * throw `TypeError` or `RangeError` before returning a result. */
26
27
  export interface Status {
27
28
  /** True when the underlying C ABI returned `kOk`. */
28
29
  ok: boolean;
@@ -519,7 +520,44 @@ export enum CalcMode {
519
520
  AutoNoTable = 2,
520
521
  }
521
522
 
522
- export type ExcelProfileId = 'mac-365-ja_JP' | 'win-365-ja_JP';
523
+ /**
524
+ * Full formula-behaviour profile id: `mac` or `win` combined with one of
525
+ * `ja_JP`, `en_US`, `de_DE`, `fr_FR`, `zh_CN`, `ko_KR`, `th_TH`, `es_ES`,
526
+ * `es_MX`, `pt_BR`, `ru_RU`, `zh_TW`, `it_IT`, `nl_NL`
527
+ * (for example `win-365-en_US`). New workbooks default to `win-365-en_US`.
528
+ * The `mac-*` ids and `win-365-ja_JP` follow Excel measurements; every other
529
+ * `win-*` id is estimated from the Mac measurements plus the Windows host
530
+ * rules.
531
+ */
532
+ export type ExcelProfileId =
533
+ | 'mac-365-ja_JP'
534
+ | 'win-365-ja_JP'
535
+ | 'mac-365-en_US'
536
+ | 'win-365-en_US'
537
+ | 'mac-365-de_DE'
538
+ | 'win-365-de_DE'
539
+ | 'mac-365-fr_FR'
540
+ | 'win-365-fr_FR'
541
+ | 'mac-365-zh_CN'
542
+ | 'win-365-zh_CN'
543
+ | 'mac-365-ko_KR'
544
+ | 'win-365-ko_KR'
545
+ | 'mac-365-th_TH'
546
+ | 'win-365-th_TH'
547
+ | 'mac-365-es_ES'
548
+ | 'win-365-es_ES'
549
+ | 'mac-365-es_MX'
550
+ | 'win-365-es_MX'
551
+ | 'mac-365-pt_BR'
552
+ | 'win-365-pt_BR'
553
+ | 'mac-365-ru_RU'
554
+ | 'win-365-ru_RU'
555
+ | 'mac-365-zh_TW'
556
+ | 'win-365-zh_TW'
557
+ | 'mac-365-it_IT'
558
+ | 'win-365-it_IT'
559
+ | 'mac-365-nl_NL'
560
+ | 'win-365-nl_NL';
523
561
 
524
562
  /**
525
563
  * A wall-clock reading in local civil fields, as read back from
@@ -610,6 +648,166 @@ export interface PaginationResult {
610
648
  horizontalBreaks: number[];
611
649
  verticalBreaks: number[];
612
650
  pageCount: number;
651
+ /** Paper the layout ran on, after the orientation swap. `known` is false
652
+ * when the stored `paperSize` was unrecognised and A4 was substituted. */
653
+ paper: PaginationPaper;
654
+ margins: PaginationMargins;
655
+ /** Cell-body rectangle before print-title reservation, from the page's top-left corner. */
656
+ printable: RectPt;
657
+ /** Effective scale as a factor (1 is 100%). */
658
+ scale: number;
659
+ /** 0 = down then over, 1 = over then down. */
660
+ pageOrder: number;
661
+ /** Repeat rows / columns in effect (0-based, inclusive); a span is meaningful only when its flag is set. */
662
+ printTitles: PaginationPrintTitles;
663
+ /** Physical pages in print order. */
664
+ pages: PaginationPage[];
665
+ /** Parallel to `horizontalBreaks`: true for a manual break. */
666
+ horizontalBreakManual: boolean[];
667
+ /** Parallel to `verticalBreaks`: true for a manual break. */
668
+ verticalBreakManual: boolean[];
669
+ }
670
+
671
+ /** `PaginationResult.paper`. `known` is false when the stored `paperSize` was
672
+ * unrecognised and A4 was substituted. */
673
+ export interface PaginationPaper {
674
+ widthPt: number;
675
+ heightPt: number;
676
+ landscape: boolean;
677
+ known: boolean;
678
+ }
679
+
680
+ /** `PaginationResult.margins`, in points; `header` / `footer` are measured
681
+ * from the page edge to the header / footer band. */
682
+ export interface PaginationMargins {
683
+ left: number;
684
+ right: number;
685
+ top: number;
686
+ bottom: number;
687
+ header: number;
688
+ footer: number;
689
+ }
690
+
691
+ /** `PaginationResult.printTitles`: repeat rows / columns (0-based,
692
+ * inclusive). A span is meaningful only when its `has*` flag is true. */
693
+ export interface PaginationPrintTitles {
694
+ hasRows: boolean;
695
+ firstRow: number;
696
+ lastRow: number;
697
+ hasCols: boolean;
698
+ firstCol: number;
699
+ lastCol: number;
700
+ }
701
+
702
+ /** A rectangle in points. */
703
+ export interface RectPt {
704
+ x: number;
705
+ y: number;
706
+ width: number;
707
+ height: number;
708
+ }
709
+
710
+ /** One physical page of a `PaginationResult`. `widthPt` / `heightPt` are the
711
+ * scaled extent of the page's own cell block (repeated titles excluded) and
712
+ * `originXPt` / `originYPt` is that block's top-left corner on the paper. */
713
+ export interface PaginationPage {
714
+ /** Index into `PaginationResult.printArea` (0 for the used-range fallback). */
715
+ areaIndex: number;
716
+ firstRow: number;
717
+ lastRow: number;
718
+ firstCol: number;
719
+ lastCol: number;
720
+ originXPt: number;
721
+ originYPt: number;
722
+ widthPt: number;
723
+ heightPt: number;
724
+ }
725
+
726
+ /** Which Windows column-width figure a geometry call uses. Mirrors `fm_geometry_mode_t`.
727
+ * `Display` is the screen figure (`Range.Width` at 96 DPI); `Print` is the
728
+ * DPI-stable figure pagination breaks on. Row heights are identical in both. */
729
+ export enum GeometryMode {
730
+ Display = 0,
731
+ Print = 1,
732
+ }
733
+
734
+ /** Return type of `Workbook.getCellRectPt(...)`. */
735
+ export interface CellRectResult extends RectPt {
736
+ status: Status;
737
+ }
738
+
739
+ /** Return type of `Workbook.getWidthModel(...)`. */
740
+ export interface WidthModelResult {
741
+ status: Status;
742
+ pointsPerChar: number;
743
+ paddingPt: number;
744
+ normalFontSize: number;
745
+ /** False when the Normal font is not a measured calibration point and the Calibri 11 figure was extrapolated. */
746
+ calibrated: boolean;
747
+ normalFontName: string;
748
+ platform: string;
749
+ }
750
+
751
+ /** Sheet default column / row metrics (`<sheetFormatPr>`). A width / height is
752
+ * meaningful only when its `has*` flag is set. */
753
+ export interface SheetFormatDefaults {
754
+ /** Character units. */
755
+ defaultColWidth: number;
756
+ /** Points. */
757
+ defaultRowHeight: number;
758
+ /** Character units; OOXML default 8. */
759
+ baseColWidth: number;
760
+ hasDefaultColWidth: boolean;
761
+ hasDefaultRowHeight: boolean;
762
+ }
763
+
764
+ /** Return type of `Workbook.getSheetFormatDefaults(sheet)`. The effective
765
+ * values are read-only and ignored by `setSheetFormatDefaults`. */
766
+ export interface SheetFormatDefaultsResult extends SheetFormatDefaults {
767
+ status: Status;
768
+ /** Character units the sheet lays columns out with: `defaultColWidth` when set, else 8.43. */
769
+ effectiveDefaultColWidth: number;
770
+ /** Points the sheet lays rows out with: `defaultRowHeight` when set, else 102/7 (about 14.57). */
771
+ effectiveDefaultRowHeight: number;
772
+ }
773
+
774
+ /** Return type of `Workbook.getFormula` / `getFormulaR1C1`. `formula` is `null` when the cell holds no formula. */
775
+ export interface FormulaResult {
776
+ status: Status;
777
+ formula: string | null;
778
+ }
779
+
780
+ /** One populated cell of `Workbook.getCellsInRange`. */
781
+ export interface RangeCell {
782
+ row: number;
783
+ col: number;
784
+ formula: string | null;
785
+ value: Value;
786
+ }
787
+
788
+ /** Return type of `Workbook.getCellsInRange(...)`. */
789
+ export interface CellsInRangeResult {
790
+ status: Status;
791
+ cells: RangeCell[];
792
+ /** Resume position for the next page, or `null` when the range is exhausted. */
793
+ nextCursor: number | null;
794
+ }
795
+
796
+ /** Outcome of a display-text rendering. Mirrors `fm_display_status_t`.
797
+ * `Overflow`: the value cannot be shown in the format and the text is
798
+ * `########`. `InvalidFormat`: the code is malformed and the text is the
799
+ * General rendering. */
800
+ export enum DisplayStatus {
801
+ Ok = 0,
802
+ Overflow = 1,
803
+ InvalidFormat = 2,
804
+ }
805
+
806
+ /** Return type of `Workbook.getDisplayText` / `formatValue`. */
807
+ export interface DisplayTextResult {
808
+ status: Status;
809
+ text: string;
810
+ displayStatus: DisplayStatus;
613
811
  }
614
812
 
615
813
  /** Sheet tab visibility, mirroring OOXML `<sheet state>`.
@@ -735,6 +933,10 @@ export interface RowLayout {
735
933
  /** Whether OOXML customFormat=1 makes the row style effective. */
736
934
  hasStyle: number;
737
935
  styleXf: number;
936
+ /** Boolean stored as 0/1: whether a height is stored; `height` is meaningful only then. */
937
+ hasHeight: number;
938
+ /** Boolean stored as 0/1: an explicit override (`customHeight="1"`) rather than an auto height Excel recomputes. */
939
+ customHeight: number;
738
940
  }
739
941
 
740
942
  /** Return type of `Workbook.getSheetRowOverrides(sheet)`. */
@@ -807,13 +1009,13 @@ export interface DataValidationRange {
807
1009
  * * `op` — 0 between, 1 notBetween, 2 equal, 3 notEqual,
808
1010
  * 4 greaterThan, 5 lessThan,
809
1011
  * 6 greaterThanOrEqual, 7 lessThanOrEqual.
810
- * * `errorStyle` — 0 stop, 1 warning, 2 information.
1012
+ * * `errorStyle` — a `ValidationErrorStyle`.
811
1013
  */
812
1014
  export interface DataValidationEntry {
813
1015
  readonly ranges: ReadonlyArray<DataValidationRange>;
814
1016
  readonly type: number;
815
1017
  readonly op: number;
816
- readonly errorStyle: number;
1018
+ readonly errorStyle: ValidationErrorStyle;
817
1019
  readonly allowBlank: boolean;
818
1020
  readonly showInputMessage: boolean;
819
1021
  readonly showErrorMessage: boolean;
@@ -837,7 +1039,7 @@ export interface DataValidationInput {
837
1039
  ranges?: ReadonlyArray<DataValidationRange>;
838
1040
  type: number;
839
1041
  op?: number;
840
- errorStyle?: number;
1042
+ errorStyle?: ValidationErrorStyle;
841
1043
  allowBlank?: boolean;
842
1044
  showInputMessage?: boolean;
843
1045
  showErrorMessage?: boolean;
@@ -863,7 +1065,51 @@ export interface CellNode {
863
1065
  readonly col: number;
864
1066
  }
865
1067
 
866
- /** Result envelope for `functionMetadata(name, locale)`.
1068
+ /** One error value's spelling under a profile: the canonical (en-invariant)
1069
+ * text and the profile's Excel spelling. `measured` is `false` when the
1070
+ * localized spelling is assumed rather than captured from Excel. */
1071
+ export interface LocaleErrorName {
1072
+ readonly canonical: string;
1073
+ readonly localized: string;
1074
+ readonly measured: boolean;
1075
+ }
1076
+
1077
+ /** Order in which a locale writes day, month and year. */
1078
+ export type LocaleDateOrder = 'mdy' | 'ymd' | 'dmy';
1079
+
1080
+ /** Scalar locale facts of one {@link ExcelProfileId}. `measured` is `true`
1081
+ * for the profiles captured from Excel (every `mac-*` id and
1082
+ * `win-365-ja_JP`) and `false` for the estimated `win-*` ids. Every
1083
+ * scalar field is captured in each Mac locale, so `measured` covers them
1084
+ * all; only `errorNames` carries per-entry flags.
1085
+ * `errorNames` is indexed by error-code ordinal. */
1086
+ export interface LocaleFacts {
1087
+ readonly decimalSeparator: string;
1088
+ readonly groupSeparator: string;
1089
+ readonly listSeparator: string;
1090
+ readonly arrayColumnSeparator: string;
1091
+ readonly arrayRowSeparator: string;
1092
+ readonly trueName: string;
1093
+ readonly falseName: string;
1094
+ readonly dateOrder: LocaleDateOrder;
1095
+ readonly currencySymbol: string;
1096
+ /** `true` when the currency symbol follows the number. */
1097
+ readonly currencySuffix: boolean;
1098
+ /** `true` when one space separates the symbol and the number. */
1099
+ readonly currencySpace: boolean;
1100
+ readonly currencyDefaultDecimals: number;
1101
+ readonly measured: boolean;
1102
+ readonly errorNames: readonly LocaleErrorName[];
1103
+ }
1104
+
1105
+ /** Return type of `Workbook.localeFacts(profileId)`. `facts` is `null` on
1106
+ * failure (an unknown profile id). */
1107
+ export interface LocaleFactsResult {
1108
+ status: Status;
1109
+ facts: LocaleFacts | null;
1110
+ }
1111
+
1112
+ /** Result envelope for `functionMetadata(name)`.
867
1113
  *
868
1114
  * `ok` is `false` when no function matches `name`; the remaining
869
1115
  * fields are absent. When `ok` is `true`, `name` / `minArity` /
@@ -930,8 +1176,8 @@ export interface MergedFunctionMetadataResult extends FunctionMetadataResult {
930
1176
  *
931
1177
  * When `entry` is `undefined`, `base` is returned verbatim (signature /
932
1178
  * description stay `undefined`). `locale` is a BCP-47 display tag matching
933
- * the keys in `aliases` / `localized`, independent of the numeric locale
934
- * passed to `functionMetadata()`. See `docs/function-metadata-schema.md`.
1179
+ * the keys in `aliases` / `localized`, independent of the profile id
1180
+ * passed to the engine locale calls. See `docs/function-metadata-schema.md`.
935
1181
  *
936
1182
  * A pure host-side helper: it touches no WASM state and is exported from
937
1183
  * this package's hand-written entry point rather than the generated module
@@ -1145,6 +1391,21 @@ export interface CellXfResult {
1145
1391
  hasWrapText: boolean;
1146
1392
  /** Whether `justifyLastLine="..."` was explicitly present. */
1147
1393
  hasJustifyLastLine: boolean;
1394
+ /** OOXML `applyNumberFormat` / `applyFont` / `applyFill` / `applyBorder` /
1395
+ * `applyAlignment` / `applyProtection`: whether this record's value for
1396
+ * the group overrides its parent named style. */
1397
+ applyNumberFormat: boolean;
1398
+ applyFont: boolean;
1399
+ applyFill: boolean;
1400
+ applyBorder: boolean;
1401
+ applyAlignment: boolean;
1402
+ applyProtection: boolean;
1403
+ /** OOXML `quotePrefix`. */
1404
+ quotePrefix: boolean;
1405
+ /** Whether the record carries a `<protection>` child. When false, `locked` / `hidden` are the model defaults (true / false). */
1406
+ hasProtection: boolean;
1407
+ locked: boolean;
1408
+ hidden: boolean;
1148
1409
  /** OOXML `textRotation`; present only when the source attribute existed. */
1149
1410
  textRotation?: number;
1150
1411
  /** OOXML `indent`; present only when the source attribute existed. */
@@ -1171,7 +1432,7 @@ export interface CellXfResult {
1171
1432
  * the writer emits the sibling `*Argb` as `rgb`. */
1172
1433
  export interface ColorSpec {
1173
1434
  /** 0=none, 1=rgb, 2=theme, 3=indexed, 4=auto. */
1174
- kind: number;
1435
+ kind: FilterKind;
1175
1436
  /** AARRGGBB; meaningful when `kind` is 1. */
1176
1437
  rgb: number;
1177
1438
  /** Theme index; meaningful when `kind` is 2. */
@@ -1278,6 +1539,21 @@ export interface CellXf {
1278
1539
  hasWrapText?: boolean;
1279
1540
  /** Whether `justifyLastLine` was explicitly supplied; defaults to inference. */
1280
1541
  hasJustifyLastLine?: boolean;
1542
+ /** OOXML `apply*` flags; each defaults to false. */
1543
+ applyNumberFormat?: boolean;
1544
+ applyFont?: boolean;
1545
+ applyFill?: boolean;
1546
+ applyBorder?: boolean;
1547
+ applyAlignment?: boolean;
1548
+ applyProtection?: boolean;
1549
+ /** OOXML `quotePrefix`; defaults to false. */
1550
+ quotePrefix?: boolean;
1551
+ /** Whether to write a `<protection>` child. Omit to infer from `locked` / `hidden`. */
1552
+ hasProtection?: boolean;
1553
+ /** Defaults to true; ignored unless the record carries a `<protection>` child. */
1554
+ locked?: boolean;
1555
+ /** Defaults to false; ignored unless the record carries a `<protection>` child. */
1556
+ hidden?: boolean;
1281
1557
  /** OOXML `textRotation` (0..180 or 255). Omitted when absent. */
1282
1558
  textRotation?: number;
1283
1559
  /** OOXML `indent` (0..255). Omitted when absent. */
@@ -1420,7 +1696,235 @@ export interface ExternalLinkRecord {
1420
1696
  * `TargetMode="External"` (the common case). */
1421
1697
  targetExternal: boolean;
1422
1698
  /** One of `ExternalLinkKind.*`. */
1423
- kind: number;
1699
+ kind: FilterKind;
1700
+ }
1701
+
1702
+ /** Argument of `Workbook.setCellStyle`. Mirrors `CellStyleResult` without the status. */
1703
+ export interface CellStyleRecord {
1704
+ /** Display name of the style. */
1705
+ name: string;
1706
+ /** Index into the `<cellStyleXfs>` table; defaults to 0. */
1707
+ xfId?: number;
1708
+ /** OOXML built-in ordinal (`0..53`); defaults to `0xFFFFFFFF` (custom). */
1709
+ builtinId?: number;
1710
+ /** Outline level of the `RowLevel_n` / `ColLevel_n` styles; defaults to 0. */
1711
+ iLevel?: number;
1712
+ hidden?: boolean;
1713
+ customBuiltin?: boolean;
1714
+ }
1715
+
1716
+ /** Criterion of an AutoFilter column. Mirrors `fm_filter_kind_t`. */
1717
+ export enum FilterKind {
1718
+ None = 0,
1719
+ Values = 1,
1720
+ Custom = 2,
1721
+ Top10 = 3,
1722
+ Dynamic = 4,
1723
+ Color = 5,
1724
+ Icon = 6,
1725
+ }
1726
+
1727
+ /** Comparison operator of a custom AutoFilter condition. Mirrors `fm_filter_operator_t`. */
1728
+ export enum FilterOperator {
1729
+ Equal = 0,
1730
+ LessThan = 1,
1731
+ LessThanOrEqual = 2,
1732
+ NotEqual = 3,
1733
+ GreaterThanOrEqual = 4,
1734
+ GreaterThan = 5,
1735
+ }
1736
+
1737
+ /** Dynamic AutoFilter type, in `ST_DynamicFilterType` schema order. Mirrors `fm_dynamic_filter_type_t`. */
1738
+ export enum DynamicFilterType {
1739
+ Null = 0,
1740
+ AboveAverage = 1,
1741
+ BelowAverage = 2,
1742
+ Tomorrow = 3,
1743
+ Today = 4,
1744
+ Yesterday = 5,
1745
+ NextWeek = 6,
1746
+ ThisWeek = 7,
1747
+ LastWeek = 8,
1748
+ NextMonth = 9,
1749
+ ThisMonth = 10,
1750
+ LastMonth = 11,
1751
+ NextQuarter = 12,
1752
+ ThisQuarter = 13,
1753
+ LastQuarter = 14,
1754
+ NextYear = 15,
1755
+ ThisYear = 16,
1756
+ LastYear = 17,
1757
+ YearToDate = 18,
1758
+ Q1 = 19,
1759
+ Q2 = 20,
1760
+ Q3 = 21,
1761
+ Q4 = 22,
1762
+ M1 = 23,
1763
+ M2 = 24,
1764
+ M3 = 25,
1765
+ M4 = 26,
1766
+ M5 = 27,
1767
+ M6 = 28,
1768
+ M7 = 29,
1769
+ M8 = 30,
1770
+ M9 = 31,
1771
+ M10 = 32,
1772
+ M11 = 33,
1773
+ M12 = 34,
1774
+ }
1775
+
1776
+ /** What a sort condition sorts by. Mirrors `fm_sort_by_t`. */
1777
+ export enum SortBy {
1778
+ Value = 0,
1779
+ CellColor = 1,
1780
+ FontColor = 2,
1781
+ Icon = 3,
1782
+ }
1783
+
1784
+ /** Sort method of an AutoFilter sort state. Mirrors `fm_sort_method_t`. */
1785
+ export enum SortMethod {
1786
+ None = 0,
1787
+ PinYin = 1,
1788
+ Stroke = 2,
1789
+ }
1790
+
1791
+ /** Granularity of an AutoFilter date-group item. Mirrors `fm_date_time_grouping_t`. */
1792
+ export enum DateTimeGrouping {
1793
+ Year = 0,
1794
+ Month = 1,
1795
+ Day = 2,
1796
+ Hour = 3,
1797
+ Minute = 4,
1798
+ Second = 5,
1799
+ }
1800
+
1801
+ /** Data-validation error style. Mirrors `fm_validation_error_style_t`. */
1802
+ export enum ValidationErrorStyle {
1803
+ Stop = 0,
1804
+ Warning = 1,
1805
+ Information = 2,
1806
+ }
1807
+
1808
+ /** Where a colour is used; decides what an automatic colour means. Mirrors `fm_color_context_t`. */
1809
+ export enum ColorContext {
1810
+ Font = 0,
1811
+ FillForeground = 1,
1812
+ FillBackground = 2,
1813
+ Border = 3,
1814
+ }
1815
+
1816
+ /** Raster format of an image; `Unknown` marks "no image bytes found". Mirrors `fm_image_format_t`. */
1817
+ export enum ImageFormat {
1818
+ Unknown = 0,
1819
+ Png = 1,
1820
+ Jpeg = 2,
1821
+ Gif = 3,
1822
+ Bmp = 4,
1823
+ }
1824
+
1825
+ /** What a drawing anchor holds. Mirrors `fm_drawing_object_kind_t`. */
1826
+ export enum DrawingObjectKind {
1827
+ Picture = 0,
1828
+ Shape = 1,
1829
+ Chart = 2,
1830
+ Group = 3,
1831
+ Connector = 4,
1832
+ GraphicFrame = 5,
1833
+ Other = 6,
1834
+ }
1835
+
1836
+ /** The anchor element type of a drawing object. Mirrors `fm_anchor_kind_t`. */
1837
+ export enum AnchorKind {
1838
+ OneCell = 0,
1839
+ TwoCell = 1,
1840
+ Absolute = 2,
1841
+ }
1842
+
1843
+ /** How a drawing object follows row and column edits. Mirrors `fm_anchor_edit_as_t`. */
1844
+ export enum AnchorEditAs {
1845
+ TwoCell = 0,
1846
+ OneCell = 1,
1847
+ Absolute = 2,
1848
+ }
1849
+
1850
+ /** How a colour was resolved. Mirrors `fm_color_resolution_t`. `Exact` is a literal or workbook-supplied
1851
+ * colour; `DefaultTheme` / `ThemeUnparseable` mean the current Excel Office (Aptos) theme was used because
1852
+ * the theme part is absent / unparseable; `IndexOutOfRange` is black; `AutoContext` is an automatic colour
1853
+ * (black for font and border, white for fills). */
1854
+ export enum ColorResolution {
1855
+ Exact = 0,
1856
+ DefaultTheme = 1,
1857
+ IndexOutOfRange = 2,
1858
+ ThemeUnparseable = 3,
1859
+ AutoContext = 4,
1860
+ }
1861
+
1862
+ /** Where `getTheme` read the theme from. Mirrors the C `out_source` values. */
1863
+ export enum ThemeSource {
1864
+ Part = 0,
1865
+ Default = 1,
1866
+ Unparseable = 2,
1867
+ }
1868
+
1869
+ /** Where `getEffectiveStyle` took its xf from. */
1870
+ export enum EffectiveStyleSource {
1871
+ Cell = 0,
1872
+ Row = 1,
1873
+ Column = 2,
1874
+ Default = 3,
1875
+ }
1876
+
1877
+ /** The theme's typefaces; `*EastAsian` is the `a:ea` face, else the `Jpan` script face. */
1878
+ export interface ThemeFonts {
1879
+ majorLatin: string;
1880
+ majorEastAsian: string;
1881
+ minorLatin: string;
1882
+ minorEastAsian: string;
1883
+ }
1884
+
1885
+ /** Return type of `Workbook.getTheme()`. */
1886
+ export interface ThemeResult {
1887
+ status: Status;
1888
+ /** One of `ThemeSource.*`. */
1889
+ source: ThemeSource;
1890
+ /** 0xFFRRGGBB in `clrScheme` order: dk1, lt1, dk2, lt2, accent1..6, hlink, folHlink. */
1891
+ colors: number[];
1892
+ fonts: ThemeFonts;
1893
+ }
1894
+
1895
+ /** A resolved colour: 0xFFRRGGBB plus how it was obtained. */
1896
+ export interface ResolvedColor {
1897
+ argb: number;
1898
+ resolution: ColorResolution;
1899
+ }
1900
+
1901
+ /** Return type of `Workbook.resolveColor(...)`. */
1902
+ export interface ResolvedColorResult extends ResolvedColor {
1903
+ status: Status;
1904
+ }
1905
+
1906
+ /** Return type of `Workbook.getEffectiveStyle(...)`. */
1907
+ export interface EffectiveStyleResult {
1908
+ status: Status;
1909
+ xfIndex: number;
1910
+ /** One of `EffectiveStyleSource.*`. */
1911
+ source: EffectiveStyleSource;
1912
+ fontIndex: number;
1913
+ fillIndex: number;
1914
+ borderIndex: number;
1915
+ font: ResolvedColor;
1916
+ fillForeground: ResolvedColor;
1917
+ fillBackground: ResolvedColor;
1918
+ borders: {
1919
+ left: ResolvedColor;
1920
+ right: ResolvedColor;
1921
+ top: ResolvedColor;
1922
+ bottom: ResolvedColor;
1923
+ diagonal: ResolvedColor;
1924
+ };
1925
+ locked: boolean;
1926
+ hidden: boolean;
1927
+ numFmtCode: string;
1424
1928
  }
1425
1929
 
1426
1930
  /** Return type of `Workbook.getCellStyle(index)`. Mirrors
@@ -1492,6 +1996,255 @@ export interface SheetAutoFilterXmlResult {
1492
1996
  xml: string;
1493
1997
  }
1494
1998
 
1999
+ /** One `<dateGroupItem>` of a values filter. `grouping` is the granularity
2000
+ * the item matches at (a `DateTimeGrouping`); fields finer than `grouping` are zero. */
2001
+ export interface AutoFilterDateGroup {
2002
+ year: number;
2003
+ month: number;
2004
+ day: number;
2005
+ hour: number;
2006
+ minute: number;
2007
+ second: number;
2008
+ grouping: DateTimeGrouping;
2009
+ }
2010
+
2011
+ /** One `<filterColumn>`. `colId` is the 0-based offset from the first column
2012
+ * of the AutoFilter range. `kind` selects the criterion and only that
2013
+ * criterion's fields are read on input (a `FilterKind`); on output every other criterion's
2014
+ * fields are zero. Custom operators `op1` / `op2` are
2015
+ * `FilterOperator`s; `dynamicType` is a `DynamicFilterType`.
2016
+ * `dxfId` of `4294967295` means absent. `iconSet` is the conditional-format
2017
+ * icon-set ordinal. Omitted input fields read as zero / false / empty,
2018
+ * except `showButton` (true) and `dxfId` (absent). */
2019
+ export interface AutoFilterColumn {
2020
+ colId: number;
2021
+ hiddenButton: boolean;
2022
+ showButton: boolean;
2023
+ kind: FilterKind;
2024
+ filterBlank: boolean;
2025
+ values: string[];
2026
+ dateGroups: AutoFilterDateGroup[];
2027
+ customAnd: boolean;
2028
+ customCount: number;
2029
+ op1: FilterOperator;
2030
+ val1: string;
2031
+ op2: FilterOperator;
2032
+ val2: string;
2033
+ top: boolean;
2034
+ percent: boolean;
2035
+ hasFilterVal: boolean;
2036
+ topVal: number;
2037
+ filterVal: number;
2038
+ dynamicType: DynamicFilterType;
2039
+ hasDynVal: boolean;
2040
+ hasDynMaxVal: boolean;
2041
+ dynVal: number;
2042
+ dynMaxVal: number;
2043
+ valIso: string;
2044
+ maxValIso: string;
2045
+ dxfId: number;
2046
+ cellColor: boolean;
2047
+ iconSet: number;
2048
+ iconId: number;
2049
+ hasIconId: boolean;
2050
+ }
2051
+
2052
+ /** One `<sortCondition>`. `sortBy` is a `SortBy`. `dxfId` is read only when `hasDxfId`, `iconId` only when
2053
+ * `hasIconId`. */
2054
+ export interface AutoFilterSortCondition {
2055
+ ref: MergeRange;
2056
+ descending: boolean;
2057
+ sortBy: SortBy;
2058
+ customList: string;
2059
+ dxfId: number;
2060
+ hasDxfId: boolean;
2061
+ iconSet: number;
2062
+ iconId: number;
2063
+ hasIconId: boolean;
2064
+ }
2065
+
2066
+ /** The `<sortState>` of an AutoFilter. `sortMethod` is a
2067
+ * `SortMethod`. */
2068
+ export interface AutoFilterSortState {
2069
+ ref: MergeRange;
2070
+ columnSort: boolean;
2071
+ caseSensitive: boolean;
2072
+ sortMethod: SortMethod;
2073
+ conditions: AutoFilterSortCondition[];
2074
+ }
2075
+
2076
+ /** A sheet or table AutoFilter. `range` includes the header row; `columns`
2077
+ * must be in strictly ascending `colId` order inside it. */
2078
+ export interface AutoFilter {
2079
+ range: MergeRange;
2080
+ columns: AutoFilterColumn[];
2081
+ sort: AutoFilterSortState | null;
2082
+ }
2083
+
2084
+ /** Result of `Workbook.getAutoFilter` / `getTableAutoFilter`. `autoFilter` is
2085
+ * `null` when there is none. */
2086
+ export interface AutoFilterResult {
2087
+ status: Status;
2088
+ autoFilter: AutoFilter | null;
2089
+ }
2090
+
2091
+ /** Result of `Workbook.evaluateAutoFilter` / `evaluateTableAutoFilter`.
2092
+ * `match[i]` tells whether body row `firstRow + i` satisfies the criteria. */
2093
+ export interface AutoFilterEvalResult {
2094
+ status: Status;
2095
+ firstRow: number;
2096
+ match: boolean[];
2097
+ }
2098
+
2099
+ /** Result of `Workbook.validateValue`. `hasRule` is false when no rule covers
2100
+ * the cell, and `valid` is then true. Otherwise `ruleIndex` indexes
2101
+ * `getValidations` and `errorStyle` is a `ValidationErrorStyle`. */
2102
+ export interface ValidationOutcomeResult {
2103
+ status: Status;
2104
+ hasRule: boolean;
2105
+ valid: boolean;
2106
+ ruleIndex: number;
2107
+ errorStyle: ValidationErrorStyle;
2108
+ }
2109
+
2110
+ /** One `@person` mention in a threaded comment's text; `start` and `length`
2111
+ * are in UTF-16 code units. */
2112
+ export interface Mention {
2113
+ personId: string;
2114
+ mentionId: string;
2115
+ start: number;
2116
+ length: number;
2117
+ }
2118
+
2119
+ /** One threaded comment: a thread's opening comment, or a reply when
2120
+ * `parentId` is non-empty. Ids are brace-wrapped uppercase GUIDs and
2121
+ * `created` is `YYYY-MM-DDTHH:MM:SS.ss`; the caller supplies both. `done`
2122
+ * is the thread's resolved state, meaningful on the opening comment only. */
2123
+ export interface ThreadedComment {
2124
+ id: string;
2125
+ row: number;
2126
+ col: number;
2127
+ personId: string;
2128
+ created: string;
2129
+ text: string;
2130
+ parentId: string;
2131
+ done: boolean;
2132
+ mentions: Mention[];
2133
+ }
2134
+
2135
+ /** One entry of the workbook's person list. */
2136
+ export interface Person {
2137
+ id: string;
2138
+ displayName: string;
2139
+ userId: string;
2140
+ providerId: string;
2141
+ }
2142
+
2143
+ /** Result of `Workbook.getThreadedComments`, in file order: each thread's
2144
+ * opening comment followed by its replies. */
2145
+ export interface ThreadedCommentsResult {
2146
+ status: Status;
2147
+ comments: ThreadedComment[];
2148
+ }
2149
+
2150
+ /** Result of `Workbook.getPersons`. */
2151
+ export interface PersonsResult {
2152
+ status: Status;
2153
+ persons: Person[];
2154
+ }
2155
+
2156
+ /** Format and pixel size of an image; zeroed when `status` is not ok. */
2157
+ export interface ImageInfoResult {
2158
+ status: Status;
2159
+ format: ImageFormat;
2160
+ pxWidth: number;
2161
+ pxHeight: number;
2162
+ }
2163
+
2164
+ /** Result of `Workbook.getImage`. `bytes` is a copy, empty on failure. */
2165
+ export interface ImageResult extends ImageInfoResult {
2166
+ bytes: Uint8Array;
2167
+ }
2168
+
2169
+ /** One anchored object of a sheet's drawing. An absolute anchor reports its
2170
+ * position from A1 as `fromColOff` (x) and `fromRowOff` (y); `toRow` /
2171
+ * `toCol` and their offsets are zero unless the anchor is two-cell. Offsets
2172
+ * and `cx` / `cy` are in EMU. `imageFormat` is non-zero for a picture whose
2173
+ * media part is present; `mediaPath` is empty for a non-picture. */
2174
+ export interface DrawingObject {
2175
+ objectId: number;
2176
+ kind: DrawingObjectKind;
2177
+ anchorKind: AnchorKind;
2178
+ editAs: AnchorEditAs;
2179
+ fromRow: number;
2180
+ fromCol: number;
2181
+ fromRowOff: number;
2182
+ fromColOff: number;
2183
+ toRow: number;
2184
+ toCol: number;
2185
+ toRowOff: number;
2186
+ toColOff: number;
2187
+ cx: number;
2188
+ cy: number;
2189
+ imageFormat: ImageFormat;
2190
+ name: string;
2191
+ descr: string;
2192
+ mediaPath: string;
2193
+ }
2194
+
2195
+ /** Placement of an inserted image. `anchorKind` is `OneCell` (default) or
2196
+ * `TwoCell`; `editAs` applies to a two-cell anchor only. `row` / `col` is
2197
+ * the 0-based top-left cell and `rowOffEmu` / `colOffEmu` the offset inside
2198
+ * it. A zero `widthEmu` / `heightEmu` means the pixel size times 9525. An
2199
+ * empty `name` becomes `Picture <id>`. */
2200
+ export interface ImageInsertOptions {
2201
+ name?: string;
2202
+ descr?: string;
2203
+ anchorKind?: AnchorKind;
2204
+ editAs?: AnchorEditAs;
2205
+ row?: number;
2206
+ col?: number;
2207
+ rowOffEmu?: number;
2208
+ colOffEmu?: number;
2209
+ widthEmu?: number;
2210
+ heightEmu?: number;
2211
+ }
2212
+
2213
+ /** Result of `Workbook.insertImage` and `Workbook.restoreImage`; `objectId` is zero on failure. */
2214
+ export interface InsertImageResult {
2215
+ status: Status;
2216
+ objectId: number;
2217
+ }
2218
+
2219
+ /** New placement of an existing picture, in the quantities `listDrawingObjects`
2220
+ * reports: `row` / `col` / `rowOffEmu` / `colOffEmu` are the top-left marker of the
2221
+ * anchor box (`fromRow` ...), `widthEmu` / `heightEmu` the picture's own unrotated
2222
+ * size (`cx` / `cy`); a zero size keeps the current one. `anchorKind` is `OneCell`
2223
+ * (default) or `TwoCell`; `editAs` applies to a two-cell anchor only. */
2224
+ export interface ImagePlacement {
2225
+ anchorKind?: AnchorKind;
2226
+ editAs?: AnchorEditAs;
2227
+ row?: number;
2228
+ col?: number;
2229
+ rowOffEmu?: number;
2230
+ colOffEmu?: number;
2231
+ widthEmu?: number;
2232
+ heightEmu?: number;
2233
+ }
2234
+
2235
+ /** Result of `Workbook.snapshotImage`. `bytes` is an opaque, versioned capture to hand
2236
+ * to `restoreImage`; it is empty on failure. */
2237
+ export interface ImageSnapshotResult {
2238
+ status: Status;
2239
+ bytes: Uint8Array;
2240
+ }
2241
+
2242
+ /** Options of `Workbook.restoreImage`. With `newId` the capture is added on top as a
2243
+ * copy with a fresh id; otherwise a picture with the same id is replaced. */
2244
+ export interface RestoreImageOptions {
2245
+ newId?: boolean;
2246
+ }
2247
+
1495
2248
  /** Result of the five raw print-settings getters. The empty `xml` string
1496
2249
  * means the sheet declares no such element. */
1497
2250
  export interface SheetPrintXmlResult {
@@ -1701,10 +2454,29 @@ export interface Workbook {
1701
2454
  * cell's text. */
1702
2455
  setCellPhoneticProperties(sheet: number, row: number, col: number, properties: PhoneticProperties): Status;
1703
2456
  setBlank(sheet: number, row: number, col: number): Status;
2457
+ /** Stores a formula. Returns `kParserUnexpectedToken` and changes nothing when the text
2458
+ * does not parse: a syntax error, or a built-in called through a sheet / workbook qualifier. */
1704
2459
  setFormula(sheet: number, row: number, col: number, formula: string): Status;
1705
2460
 
1706
2461
  getValue(sheet: number, row: number, col: number): CellResult;
1707
2462
 
2463
+ /** The stored A1 formula (leading `=` included), or `formula: null` for a cell that holds none.
2464
+ * The text is returned as entered; a formula loaded from a file shows book names, not `[N]` indexes. */
2465
+ getFormula(sheet: number, row: number, col: number): FormulaResult;
2466
+ /** The formula in R1C1 notation relative to the cell, without a leading `=`; `formula: null` when the cell holds none.
2467
+ * A formula loaded from a file that does not parse is kept verbatim, evaluates to `#NAME?`, and fails here with
2468
+ * `kParserUnexpectedToken`; `setFormula` never produces that state.
2469
+ * Sheet and external qualifiers are quoted as a whole only when the path, book or sheet name needs it. */
2470
+ getFormulaR1C1(sheet: number, row: number, col: number): FormulaResult;
2471
+ /** One page of the populated cells (formula or non-blank value, spill phantoms included) inside
2472
+ * `range`, row-major. `cursor` is the `nextCursor` of the previous page (omit for the first);
2473
+ * `limit` caps the page (omit or 0 for the maximum, 65536). */
2474
+ getCellsInRange(sheet: number, range: MergeRange, cursor?: number | null, limit?: number | null): CellsInRangeResult;
2475
+ /** The text Excel displays for the cell, from its value and number format under the workbook's date system. */
2476
+ getDisplayText(sheet: number, row: number, col: number): DisplayTextResult;
2477
+ /** Renders `value` (blank, number, boolean, text or error) under the stored-form number format `formatCode`; empty means General. */
2478
+ formatValue(value: Value, formatCode: string): DisplayTextResult;
2479
+
1708
2480
  /** Evaluates `formula` as if entered at `(sheet, row, col)` and returns a
1709
2481
  * single scalar result, without mutating the workbook. Local and
1710
2482
  * cross-sheet references, defined names, and `ROW()` / `COLUMN()` resolve
@@ -1832,8 +2604,8 @@ export interface Workbook {
1832
2604
  setPinnedNow(year: number, month: number, day: number, hour: number, minute: number, second: number): Status;
1833
2605
  clearPinnedNow(): Status;
1834
2606
 
1835
- /**
1836
- * Full formula-behaviour profile id. Defaults to `win-365-ja_JP`.
2607
+ /** Full formula-behaviour profile id. Defaults to `win-365-en_US`.
2608
+ * Pick another locale or host with any {@link ExcelProfileId}.
1837
2609
  */
1838
2610
  excelProfileId(): StringResult<ExcelProfileId>;
1839
2611
  setExcelProfileId(profileId: ExcelProfileId): Status;
@@ -1844,13 +2616,15 @@ export interface Workbook {
1844
2616
  * hyperlinks, tables, print areas, manual breaks and the auto-filter
1845
2617
  * range. The ranges and formulas inside the worksheet `<extLst>` (the
1846
2618
  * `x14` conditional-formatting block, sparkline groups, `x14`
1847
- * validations) move with them, as Excel moves them.
2619
+ * validations) move with them, as Excel moves them, and so do the cells
2620
+ * named by the other worksheet content kept verbatim for a lossless save:
2621
+ * protected ranges, scenarios, a sheet sort state, cell watches,
2622
+ * ignored-error ranges and web-publish ranges.
1848
2623
  *
1849
- * They do not move an unmodelled `<worksheet>` child kept byte-verbatim
1850
- * so a save does not drop it (a `<sortState>`, for one): a `ref` inside
1851
- * it keeps its pre-edit rectangle, and nothing reports it. An insert also
1852
- * does not copy the formatting of the row or column before it onto the
1853
- * new one, which Excel does — a sparkline included.
2624
+ * They do not move the anchor of an embedded OLE object or form control,
2625
+ * also kept verbatim: it keeps its pre-edit cell, and nothing reports it.
2626
+ * An insert also does not copy the formatting of the row or column before
2627
+ * it onto the new one, which Excel does — a sparkline included.
1854
2628
  */
1855
2629
 
1856
2630
  /** Inserts `count` rows at `row` on `sheet` and rewrites cross-workbook
@@ -1870,10 +2644,12 @@ export interface Workbook {
1870
2644
  definedNameCount(): NumberResult;
1871
2645
  definedNameAt(idx: number): DefinedNameEntry;
1872
2646
  /** Adds, replaces, or (when `formula` is empty) removes a workbook-
1873
- * scoped defined name. */
2647
+ * scoped defined name. A non-empty `formula` that does not parse is
2648
+ * rejected with `kParserUnexpectedToken`. */
1874
2649
  setDefinedName(name: string, formula: string): Status;
1875
2650
  /** Adds, replaces, or removes a defined name in workbook scope (-1)
1876
- * or a sheet-local scope (0-based sheet index). */
2651
+ * or a sheet-local scope (0-based sheet index). A non-empty `formula`
2652
+ * that does not parse is rejected with `kParserUnexpectedToken`. */
1877
2653
  setDefinedNameScoped(name: string, formula: string, localSheetId: number): Status;
1878
2654
 
1879
2655
  tableCount(): NumberResult;
@@ -1890,6 +2666,73 @@ export interface Workbook {
1890
2666
  /** Replaces the worksheet-level `<autoFilter>` XML fragment; empty clears it. */
1891
2667
  setSheetAutoFilterXml(sheet: number, xml: string): Status;
1892
2668
 
2669
+ /** Reads the sheet's typed AutoFilter; `autoFilter` is `null` when absent. */
2670
+ getAutoFilter(sheet: number): AutoFilterResult;
2671
+ /** Replaces the sheet AutoFilter and its hidden `_xlnm._FilterDatabase`
2672
+ * name. Row visibility is unchanged; call `applyAutoFilter` to hide the
2673
+ * excluded rows. */
2674
+ setAutoFilter(sheet: number, filter: AutoFilter): Status;
2675
+ /** Removes the sheet AutoFilter. Row visibility is unchanged. */
2676
+ removeAutoFilter(sheet: number): Status;
2677
+ /** Hides every body row the criteria exclude and shows the rest, as
2678
+ * Excel's Reapply does. Fails with a not-found status when there is no AutoFilter. */
2679
+ applyAutoFilter(sheet: number): Status;
2680
+ /** Drops every column criterion and shows all body rows. */
2681
+ clearAutoFilter(sheet: number): Status;
2682
+ /** Evaluates the sheet AutoFilter without changing the sheet. */
2683
+ evaluateAutoFilter(sheet: number): AutoFilterEvalResult;
2684
+ /** Table counterparts, addressed by the workbook-wide table index
2685
+ * (`tableAt`). */
2686
+ getTableAutoFilter(table: number): AutoFilterResult;
2687
+ setTableAutoFilter(table: number, filter: AutoFilter): Status;
2688
+ removeTableAutoFilter(table: number): Status;
2689
+ applyTableAutoFilter(table: number): Status;
2690
+ clearTableAutoFilter(table: number): Status;
2691
+ evaluateTableAutoFilter(table: number): AutoFilterEvalResult;
2692
+
2693
+ /** Checks `value` against the validation rule covering `(row, col)` without
2694
+ * storing it. The first rule in `getValidations` order wins on overlap. */
2695
+ validateValue(sheet: number, row: number, col: number, value: Value): ValidationOutcomeResult;
2696
+ /** Enumerates populated cells whose value fails their validation rule, in
2697
+ * row-major order, one page at a time; paging as `getCellsInRange`. */
2698
+ listInvalidCells(sheet: number, cursor?: number | null, limit?: number | null): CellsInRangeResult;
2699
+
2700
+ /** Lists the sheet's threaded comments, replies included. */
2701
+ getThreadedComments(sheet: number): ThreadedCommentsResult;
2702
+ /** Adds a threaded comment. An empty `parentId` opens a new thread at
2703
+ * `row` / `col`; otherwise it replies to that thread. */
2704
+ addThreadedComment(sheet: number, comment: Partial<ThreadedComment> & Pick<ThreadedComment, 'id' | 'text'>): Status;
2705
+ /** Replaces the text and mentions of the comment with `id`. */
2706
+ editThreadedComment(sheet: number, id: string, text: string, mentions: Mention[]): Status;
2707
+ /** Sets the resolved state of the thread opened by `threadId`. */
2708
+ setThreadResolved(sheet: number, threadId: string, done: boolean): Status;
2709
+ /** Removes a comment; removing an opening comment removes its thread. */
2710
+ removeThreadedComment(sheet: number, id: string): Status;
2711
+ /** Lists the workbook's persons. */
2712
+ getPersons(): PersonsResult;
2713
+ addPerson(person: Person): Status;
2714
+ /** Fails while a threaded comment or mention still names the person. */
2715
+ removePerson(id: string): Status;
2716
+
2717
+ /** Sniffs the format and pixel size of PNG, JPEG, GIF or BMP bytes without touching the workbook. */
2718
+ probeImage(bytes: Uint8Array): ImageInfoResult;
2719
+ /** Lists the anchored objects of the sheet's drawing, in document order. */
2720
+ listDrawingObjects(sheet: number): ListResult<DrawingObject>;
2721
+ /** Returns a copy of the media bytes of the picture `objectId`. */
2722
+ getImage(sheet: number, objectId: number): ImageResult;
2723
+ /** Inserts `bytes` as a picture; existing drawing content is kept. */
2724
+ insertImage(sheet: number, bytes: Uint8Array, opts?: ImageInsertOptions): InsertImageResult;
2725
+ /** Removes the picture `objectId` and its media once nothing else references it. */
2726
+ removeImage(sheet: number, objectId: number): Status;
2727
+ /** Moves and resizes the picture `objectId`, keeping its id, crop, rotation and every other element. */
2728
+ setImageAnchor(sheet: number, objectId: number, placement: ImagePlacement): Status;
2729
+ /** Makes the picture `objectId` item `index` of `listDrawingObjects`, whose order is the stacking order (0 is the back). */
2730
+ setImageZOrder(sheet: number, objectId: number, index: number): Status;
2731
+ /** Captures the picture `objectId` with its list position, element and media as opaque bytes for `restoreImage`. */
2732
+ snapshotImage(sheet: number, objectId: number): ImageSnapshotResult;
2733
+ /** Puts a `snapshotImage` capture back and returns the picture's id: in place of a picture with the same id at its recorded position, or as a copy on top with `newId`. */
2734
+ restoreImage(sheet: number, bytes: Uint8Array, opts?: RestoreImageOptions): InsertImageResult;
2735
+
1893
2736
  passthroughCount(): NumberResult;
1894
2737
  passthroughAt(idx: number): PassthroughEntry;
1895
2738
 
@@ -2226,6 +3069,29 @@ export interface Workbook {
2226
3069
  setRowHidden(sheet: number, row: number, hidden: boolean): Status;
2227
3070
  /** Sets / replaces the row outline level at `row` (clamped to 0..255). */
2228
3071
  setRowOutline(sheet: number, row: number, level: number): Status;
3072
+ /** Removes the height override at `row`, returning it to the sheet default. */
3073
+ clearRowHeight(sheet: number, row: number): Status;
3074
+ /** Removes the width override on columns `first..last`, returning them to the sheet default width. Hidden state, outline level and column style are kept. */
3075
+ clearColumnWidth(sheet: number, first: number, last: number): Status;
3076
+
3077
+ /** Reads the sheet's default column / row metrics. */
3078
+ getSheetFormatDefaults(sheet: number): SheetFormatDefaultsResult;
3079
+ /** Replaces the sheet's default column / row metrics. A `has*` flag left out defaults to whether its value was supplied. */
3080
+ setSheetFormatDefaults(sheet: number, defaults: Partial<SheetFormatDefaults>): Status;
3081
+
3082
+ /** Rectangle covering the inclusive cell range, in points from the top-left of A1.
3083
+ * Hidden rows and columns contribute zero extent. */
3084
+ getCellRectPt(sheet: number, range: MergeRange, mode: GeometryMode): CellRectResult;
3085
+ /** Effective column width in points; zero when hidden. */
3086
+ getColumnWidthPt(sheet: number, col: number, mode: GeometryMode): NumberResult;
3087
+ /** Effective row height in points; zero when hidden. */
3088
+ getRowHeightPt(sheet: number, row: number): NumberResult;
3089
+ /** The character-unit to point conversion model for the workbook's Normal font. */
3090
+ getWidthModel(sheet: number, mode: GeometryMode): WidthModelResult;
3091
+ /** Converts a column width in characters to points. */
3092
+ columnCharsToPt(sheet: number, mode: GeometryMode, chars: number): NumberResult;
3093
+ /** Inverse of `columnCharsToPt`; a width at or below the padding maps to zero characters. */
3094
+ columnPtToChars(sheet: number, mode: GeometryMode, pt: number): NumberResult;
2229
3095
 
2230
3096
  /** Returns `{ status, xfIndex }` for the cell at `(sheet, row, col)`. */
2231
3097
  getCellXfIndex(sheet: number, row: number, col: number): CellXfIndexResult;
@@ -2316,15 +3182,39 @@ export interface Workbook {
2316
3182
  * `<cellStyleXfs>` index, which is what `setCellStyle` and
2317
3183
  * `CellXf.xfId` reference. */
2318
3184
  addCellStyleXf(record: CellXf): AddStyleResult;
2319
- /** Adds or replaces the `<cellStyle>` entry named `name`. `builtinId` is
2320
- * an OOXML ordinal `0..47`, or `0xFFFFFFFF` for a custom style; it is
2321
- * required because the binding takes a fixed argument count. */
2322
- setCellStyle(name: string, xfId: number, builtinId: number): Status;
3185
+ /** Adds or replaces the `<cellStyle>` entry named `record.name`. Absent
3186
+ * fields default to `xfId` 0, a custom style (`0xFFFFFFFF`), level 0 and
3187
+ * both flags false. */
3188
+ setCellStyle(record: CellStyleRecord): Status;
3189
+ /** Removes the `<cellStyle>` named `name`; cell formats that used it are
3190
+ * repointed at the Normal style. */
3191
+ removeCellStyle(name: string): Status;
3192
+
3193
+ /** The 12 theme colours (`clrScheme` order) and the theme typefaces. The
3194
+ * default theme is reported when the part is absent or unparseable;
3195
+ * `source` tells the cases apart. */
3196
+ getTheme(): ThemeResult;
3197
+ /** Rewrites the 12 scheme colours (`clrScheme` order, alpha ignored). A
3198
+ * workbook without a theme part first gets a minimal one. */
3199
+ setThemeColors(colors: number[]): Status;
3200
+ /** Rewrites the theme's major and minor typefaces. */
3201
+ setThemeFonts(fonts: ThemeFonts): Status;
3202
+ /** Removes the theme part so the workbook reports the default theme (`source` is `Default`). Excel adds a theme part again when it saves the file. */
3203
+ resetTheme(): Status;
3204
+ /** Resolves a colour specification to ARGB against the theme and the
3205
+ * indexed palette; `context` decides what an automatic colour means. */
3206
+ resolveColor(spec: ColorSpec, context: ColorContext): ResolvedColorResult;
3207
+ /** The formatting a cell shows: the xf chosen from cell, row, column or
3208
+ * the default, with its colours resolved. Conditional formatting is not
3209
+ * applied. */
3210
+ getEffectiveStyle(sheet: number, row: number, col: number): EffectiveStyleResult;
2323
3211
 
2324
3212
  /** Returns every external-link record carried by the workbook in
2325
3213
  * `<externalReferences>` document order. Empty for fresh workbooks
2326
3214
  * and any package whose source archive had no `<externalReferences>`
2327
- * block. */
3215
+ * block. A formula, name, conditional-format rule or data validation that names an unregistered
3216
+ * book (bracket or path spelling) appends a record without renumbering; a book already present,
3217
+ * in any letter case, adds none. */
2328
3218
  getExternalLinks(): ListResult<ExternalLinkRecord>;
2329
3219
 
2330
3220
  /** Adds a merge range to `sheet`. */
@@ -2337,6 +3227,8 @@ export interface Workbook {
2337
3227
  clearMerges(sheet: number): Status;
2338
3228
  /** Returns every merge range on `sheet` as a JS array. */
2339
3229
  getMerges(sheet: number): ListResult<MergeRange>;
3230
+ /** Returns the merge ranges on `sheet` that intersect `range`, in storage order. */
3231
+ getMergesInRange(sheet: number, range: MergeRange): ListResult<MergeRange>;
2340
3232
 
2341
3233
  /** Returns the cell comment at `(sheet, row, col)`, or `null` when absent. */
2342
3234
  getComment(sheet: number, row: number, col: number): CommentEntry | null;
@@ -2386,7 +3278,8 @@ export interface Workbook {
2386
3278
  * cell-range list; the rule itself surfaces its raw OOXML payload
2387
3279
  * (the engine does not yet evaluate validation rules). */
2388
3280
  getValidations(sheet: number): ListResult<DataValidationEntry>;
2389
- /** Appends a data-validation rule to `sheet`. */
3281
+ /** Appends a data-validation rule to `sheet`. A non-empty `formula1` / `formula2`
3282
+ * that does not parse is rejected with `kParserUnexpectedToken`. */
2390
3283
  addValidation(sheet: number, validation: DataValidationInput): Status;
2391
3284
  /** Removes the validation rule at `index`. Returns `kInvalidArgument`
2392
3285
  * if `index` is out of range. */
@@ -2403,7 +3296,9 @@ export interface Workbook {
2403
3296
  * `index` is the new rule's position in the sheet's flattened CF rule
2404
3297
  * sequence (the same indexing `getConditionalFormats` and
2405
3298
  * `removeConditionalFormatAt` use); it stays valid until a subsequent
2406
- * add/remove/clear mutation on the same sheet renumbers the sequence. */
3299
+ * add/remove/clear mutation on the same sheet renumbers the sequence.
3300
+ * A non-empty `formula1` / `formula2` that does not parse is rejected
3301
+ * with `kParserUnexpectedToken`. */
2407
3302
  addConditionalFormat(sheet: number, rule: ConditionalFormatInput): AddStyleResult;
2408
3303
  /** Removes the CF rule at `index` (flattened order). When the
2409
3304
  * containing block becomes empty it is removed too. */
@@ -2422,28 +3317,40 @@ export interface Workbook {
2422
3317
  dependents(sheet: number, row: number, col: number, depth: number): ListResult<CellNode>;
2423
3318
 
2424
3319
  /** Returns metadata for the function `name` (case-insensitive). When
2425
- * the function is unknown, returns `{ok: false}`. `locale` selects
2426
- * the catalog locale (`0` = `en-US`, `1` = `ja-JP`) and is validated,
2427
- * but does not change the result: the description / signature fields
2428
- * are always `undefined` (see {@link FunctionMetadataResult}). */
2429
- functionMetadata(name: string, locale: number): FunctionMetadataResult;
3320
+ * the function is unknown, returns `{ok: false}`. The result is
3321
+ * locale-invariant: the description / signature fields are always
3322
+ * `undefined` (see {@link FunctionMetadataResult}). */
3323
+ functionMetadata(name: string): FunctionMetadataResult;
2430
3324
  /** Returns every registered function's canonical name in ascending
2431
3325
  * sort order. */
2432
3326
  functionNames(): ListResult<string>;
2433
3327
 
2434
3328
  /** Returns the localized display name for the canonical function
2435
- * `canonicalName` in `locale`. No alias table exists in any locale,
2436
- * so this always returns the canonical name unchanged; localized
2437
- * display names belong to the host's provider document. `value` is
2438
- * the empty string, with `status.ok === false`, when the canonical
2439
- * name does not match a registered function. */
2440
- localizeFunctionName(canonicalName: string, locale: number): StringResult;
3329
+ * `canonicalName` under `profileId`. `de_DE` and `fr_FR` profiles return
3330
+ * Excel's function names for that locale; `ja_JP` renames only `DOLLAR`,
3331
+ * `USDOLLAR` and `DBCS`; the other locales return the canonical name
3332
+ * unchanged. `value` is the empty string, with `status.ok === false`,
3333
+ * when `profileId` is unknown or the name does not match a registered
3334
+ * function. */
3335
+ localizeFunctionName(canonicalName: string, profileId: ExcelProfileId): StringResult;
2441
3336
  /** Inverse of `localizeFunctionName`: returns the canonical English
2442
- * name for the localized function `localizedName`. With no alias
2443
- * table this is a case-insensitive canonical-name match, in every
2444
- * locale. `value` is the empty string, with `status.ok === false`,
2445
- * when no function matches. */
2446
- canonicalizeFunctionName(localizedName: string, locale: number): StringResult;
3337
+ * name for the localized function `localizedName` under `profileId`.
3338
+ * `value` is the empty string, with `status.ok === false`, when
3339
+ * `profileId` is unknown or no function matches. */
3340
+ canonicalizeFunctionName(localizedName: string, profileId: ExcelProfileId): StringResult;
3341
+ /** Rewrites stored (en-invariant) formula text into `profileId`'s Excel
3342
+ * spelling: function names, list / array separators, decimal points,
3343
+ * booleans and error names. Strings, quoted sheet names, external
3344
+ * qualifiers and structured-reference brackets are kept verbatim. A pure
3345
+ * text rewrite; the grammar is not validated. `status.ok` is `false`
3346
+ * for an unknown `profileId`. */
3347
+ localizeFormula(formula: string, profileId: ExcelProfileId): StringResult;
3348
+ /** Inverse of `localizeFormula`: rewrites `profileId`-spelled formula text
3349
+ * into the en-invariant form. */
3350
+ canonicalizeFormula(formula: string, profileId: ExcelProfileId): StringResult;
3351
+ /** Returns the locale facts (separators, boolean names, date order,
3352
+ * currency, error names) of `profileId`. */
3353
+ localeFacts(profileId: ExcelProfileId): LocaleFactsResult;
2447
3354
 
2448
3355
  /** Returns dynamic-array spill info for `(sheet, row, col)`.
2449
3356
  * When the cell is part of a spill region (anchor or phantom),