@libraz/formulon 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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;
@@ -610,6 +611,161 @@ export interface PaginationResult {
610
611
  horizontalBreaks: number[];
611
612
  verticalBreaks: number[];
612
613
  pageCount: number;
614
+ /** Paper the layout ran on, after the orientation swap. `known` is false
615
+ * when the stored `paperSize` was unrecognised and A4 was substituted. */
616
+ paper: PaginationPaper;
617
+ margins: PaginationMargins;
618
+ /** Cell-body rectangle before print-title reservation, from the page's top-left corner. */
619
+ printable: RectPt;
620
+ /** Effective scale as a factor (1 is 100%). */
621
+ scale: number;
622
+ /** 0 = down then over, 1 = over then down. */
623
+ pageOrder: number;
624
+ /** Repeat rows / columns in effect (0-based, inclusive); a span is meaningful only when its flag is set. */
625
+ printTitles: PaginationPrintTitles;
626
+ /** Physical pages in print order. */
627
+ pages: PaginationPage[];
628
+ /** Parallel to `horizontalBreaks`: true for a manual break. */
629
+ horizontalBreakManual: boolean[];
630
+ /** Parallel to `verticalBreaks`: true for a manual break. */
631
+ verticalBreakManual: boolean[];
632
+ }
633
+
634
+ /** `PaginationResult.paper`. `known` is false when the stored `paperSize` was
635
+ * unrecognised and A4 was substituted. */
636
+ export interface PaginationPaper {
637
+ widthPt: number;
638
+ heightPt: number;
639
+ landscape: boolean;
640
+ known: boolean;
641
+ }
642
+
643
+ /** `PaginationResult.margins`, in points; `header` / `footer` are measured
644
+ * from the page edge to the header / footer band. */
645
+ export interface PaginationMargins {
646
+ left: number;
647
+ right: number;
648
+ top: number;
649
+ bottom: number;
650
+ header: number;
651
+ footer: number;
652
+ }
653
+
654
+ /** `PaginationResult.printTitles`: repeat rows / columns (0-based,
655
+ * inclusive). A span is meaningful only when its `has*` flag is true. */
656
+ export interface PaginationPrintTitles {
657
+ hasRows: boolean;
658
+ firstRow: number;
659
+ lastRow: number;
660
+ hasCols: boolean;
661
+ firstCol: number;
662
+ lastCol: number;
663
+ }
664
+
665
+ /** A rectangle in points. */
666
+ export interface RectPt {
667
+ x: number;
668
+ y: number;
669
+ width: number;
670
+ height: number;
671
+ }
672
+
673
+ /** One physical page of a `PaginationResult`. `widthPt` / `heightPt` are the
674
+ * scaled extent of the page's own cell block (repeated titles excluded) and
675
+ * `originXPt` / `originYPt` is that block's top-left corner on the paper. */
676
+ export interface PaginationPage {
677
+ /** Index into `PaginationResult.printArea` (0 for the used-range fallback). */
678
+ areaIndex: number;
679
+ firstRow: number;
680
+ lastRow: number;
681
+ firstCol: number;
682
+ lastCol: number;
683
+ originXPt: number;
684
+ originYPt: number;
685
+ widthPt: number;
686
+ heightPt: number;
687
+ }
688
+
689
+ /** Which Windows column-width figure a geometry call uses. Mirrors `fm_geometry_mode_t`.
690
+ * `Display` is the screen figure (`Range.Width` at 96 DPI); `Print` is the
691
+ * DPI-stable figure pagination breaks on. Row heights are identical in both. */
692
+ export enum GeometryMode {
693
+ Display = 0,
694
+ Print = 1,
695
+ }
696
+
697
+ /** Return type of `Workbook.getCellRectPt(...)`. */
698
+ export interface CellRectResult extends RectPt {
699
+ status: Status;
700
+ }
701
+
702
+ /** Return type of `Workbook.getWidthModel(...)`. */
703
+ export interface WidthModelResult {
704
+ status: Status;
705
+ pointsPerChar: number;
706
+ paddingPt: number;
707
+ normalFontSize: number;
708
+ /** False when the Normal font is not a measured calibration point and the Calibri 11 figure was extrapolated. */
709
+ calibrated: boolean;
710
+ normalFontName: string;
711
+ platform: string;
712
+ }
713
+
714
+ /** Sheet default column / row metrics (`<sheetFormatPr>`). A width / height is
715
+ * meaningful only when its `has*` flag is set. */
716
+ export interface SheetFormatDefaults {
717
+ /** Character units. */
718
+ defaultColWidth: number;
719
+ /** Points. */
720
+ defaultRowHeight: number;
721
+ /** Character units; OOXML default 8. */
722
+ baseColWidth: number;
723
+ hasDefaultColWidth: boolean;
724
+ hasDefaultRowHeight: boolean;
725
+ }
726
+
727
+ /** Return type of `Workbook.getSheetFormatDefaults(sheet)`. */
728
+ export interface SheetFormatDefaultsResult extends SheetFormatDefaults {
729
+ status: Status;
730
+ }
731
+
732
+ /** Return type of `Workbook.getFormula` / `getFormulaR1C1`. `formula` is `null` when the cell holds no formula. */
733
+ export interface FormulaResult {
734
+ status: Status;
735
+ formula: string | null;
736
+ }
737
+
738
+ /** One populated cell of `Workbook.getCellsInRange`. */
739
+ export interface RangeCell {
740
+ row: number;
741
+ col: number;
742
+ formula: string | null;
743
+ value: Value;
744
+ }
745
+
746
+ /** Return type of `Workbook.getCellsInRange(...)`. */
747
+ export interface CellsInRangeResult {
748
+ status: Status;
749
+ cells: RangeCell[];
750
+ /** Resume position for the next page, or `null` when the range is exhausted. */
751
+ nextCursor: number | null;
752
+ }
753
+
754
+ /** Outcome of a display-text rendering. Mirrors `fm_display_status_t`.
755
+ * `Overflow`: the value cannot be shown in the format and the text is
756
+ * `########`. `InvalidFormat`: the code is malformed and the text is the
757
+ * General rendering. */
758
+ export enum DisplayStatus {
759
+ Ok = 0,
760
+ Overflow = 1,
761
+ InvalidFormat = 2,
762
+ }
763
+
764
+ /** Return type of `Workbook.getDisplayText` / `formatValue`. */
765
+ export interface DisplayTextResult {
766
+ status: Status;
767
+ text: string;
768
+ displayStatus: DisplayStatus;
613
769
  }
614
770
 
615
771
  /** Sheet tab visibility, mirroring OOXML `<sheet state>`.
@@ -735,6 +891,10 @@ export interface RowLayout {
735
891
  /** Whether OOXML customFormat=1 makes the row style effective. */
736
892
  hasStyle: number;
737
893
  styleXf: number;
894
+ /** Boolean stored as 0/1: whether a height is stored; `height` is meaningful only then. */
895
+ hasHeight: number;
896
+ /** Boolean stored as 0/1: an explicit override (`customHeight="1"`) rather than an auto height Excel recomputes. */
897
+ customHeight: number;
738
898
  }
739
899
 
740
900
  /** Return type of `Workbook.getSheetRowOverrides(sheet)`. */
@@ -807,13 +967,13 @@ export interface DataValidationRange {
807
967
  * * `op` — 0 between, 1 notBetween, 2 equal, 3 notEqual,
808
968
  * 4 greaterThan, 5 lessThan,
809
969
  * 6 greaterThanOrEqual, 7 lessThanOrEqual.
810
- * * `errorStyle` — 0 stop, 1 warning, 2 information.
970
+ * * `errorStyle` — a `ValidationErrorStyle`.
811
971
  */
812
972
  export interface DataValidationEntry {
813
973
  readonly ranges: ReadonlyArray<DataValidationRange>;
814
974
  readonly type: number;
815
975
  readonly op: number;
816
- readonly errorStyle: number;
976
+ readonly errorStyle: ValidationErrorStyle;
817
977
  readonly allowBlank: boolean;
818
978
  readonly showInputMessage: boolean;
819
979
  readonly showErrorMessage: boolean;
@@ -837,7 +997,7 @@ export interface DataValidationInput {
837
997
  ranges?: ReadonlyArray<DataValidationRange>;
838
998
  type: number;
839
999
  op?: number;
840
- errorStyle?: number;
1000
+ errorStyle?: ValidationErrorStyle;
841
1001
  allowBlank?: boolean;
842
1002
  showInputMessage?: boolean;
843
1003
  showErrorMessage?: boolean;
@@ -1145,6 +1305,21 @@ export interface CellXfResult {
1145
1305
  hasWrapText: boolean;
1146
1306
  /** Whether `justifyLastLine="..."` was explicitly present. */
1147
1307
  hasJustifyLastLine: boolean;
1308
+ /** OOXML `applyNumberFormat` / `applyFont` / `applyFill` / `applyBorder` /
1309
+ * `applyAlignment` / `applyProtection`: whether this record's value for
1310
+ * the group overrides its parent named style. */
1311
+ applyNumberFormat: boolean;
1312
+ applyFont: boolean;
1313
+ applyFill: boolean;
1314
+ applyBorder: boolean;
1315
+ applyAlignment: boolean;
1316
+ applyProtection: boolean;
1317
+ /** OOXML `quotePrefix`. */
1318
+ quotePrefix: boolean;
1319
+ /** Whether the record carries a `<protection>` child. When false, `locked` / `hidden` are the model defaults (true / false). */
1320
+ hasProtection: boolean;
1321
+ locked: boolean;
1322
+ hidden: boolean;
1148
1323
  /** OOXML `textRotation`; present only when the source attribute existed. */
1149
1324
  textRotation?: number;
1150
1325
  /** OOXML `indent`; present only when the source attribute existed. */
@@ -1171,7 +1346,7 @@ export interface CellXfResult {
1171
1346
  * the writer emits the sibling `*Argb` as `rgb`. */
1172
1347
  export interface ColorSpec {
1173
1348
  /** 0=none, 1=rgb, 2=theme, 3=indexed, 4=auto. */
1174
- kind: number;
1349
+ kind: FilterKind;
1175
1350
  /** AARRGGBB; meaningful when `kind` is 1. */
1176
1351
  rgb: number;
1177
1352
  /** Theme index; meaningful when `kind` is 2. */
@@ -1278,6 +1453,21 @@ export interface CellXf {
1278
1453
  hasWrapText?: boolean;
1279
1454
  /** Whether `justifyLastLine` was explicitly supplied; defaults to inference. */
1280
1455
  hasJustifyLastLine?: boolean;
1456
+ /** OOXML `apply*` flags; each defaults to false. */
1457
+ applyNumberFormat?: boolean;
1458
+ applyFont?: boolean;
1459
+ applyFill?: boolean;
1460
+ applyBorder?: boolean;
1461
+ applyAlignment?: boolean;
1462
+ applyProtection?: boolean;
1463
+ /** OOXML `quotePrefix`; defaults to false. */
1464
+ quotePrefix?: boolean;
1465
+ /** Whether to write a `<protection>` child. Omit to infer from `locked` / `hidden`. */
1466
+ hasProtection?: boolean;
1467
+ /** Defaults to true; ignored unless the record carries a `<protection>` child. */
1468
+ locked?: boolean;
1469
+ /** Defaults to false; ignored unless the record carries a `<protection>` child. */
1470
+ hidden?: boolean;
1281
1471
  /** OOXML `textRotation` (0..180 or 255). Omitted when absent. */
1282
1472
  textRotation?: number;
1283
1473
  /** OOXML `indent` (0..255). Omitted when absent. */
@@ -1420,7 +1610,235 @@ export interface ExternalLinkRecord {
1420
1610
  * `TargetMode="External"` (the common case). */
1421
1611
  targetExternal: boolean;
1422
1612
  /** One of `ExternalLinkKind.*`. */
1423
- kind: number;
1613
+ kind: FilterKind;
1614
+ }
1615
+
1616
+ /** Argument of `Workbook.setCellStyle`. Mirrors `CellStyleResult` without the status. */
1617
+ export interface CellStyleRecord {
1618
+ /** Display name of the style. */
1619
+ name: string;
1620
+ /** Index into the `<cellStyleXfs>` table; defaults to 0. */
1621
+ xfId?: number;
1622
+ /** OOXML built-in ordinal (`0..53`); defaults to `0xFFFFFFFF` (custom). */
1623
+ builtinId?: number;
1624
+ /** Outline level of the `RowLevel_n` / `ColLevel_n` styles; defaults to 0. */
1625
+ iLevel?: number;
1626
+ hidden?: boolean;
1627
+ customBuiltin?: boolean;
1628
+ }
1629
+
1630
+ /** Criterion of an AutoFilter column. Mirrors `fm_filter_kind_t`. */
1631
+ export enum FilterKind {
1632
+ None = 0,
1633
+ Values = 1,
1634
+ Custom = 2,
1635
+ Top10 = 3,
1636
+ Dynamic = 4,
1637
+ Color = 5,
1638
+ Icon = 6,
1639
+ }
1640
+
1641
+ /** Comparison operator of a custom AutoFilter condition. Mirrors `fm_filter_operator_t`. */
1642
+ export enum FilterOperator {
1643
+ Equal = 0,
1644
+ LessThan = 1,
1645
+ LessThanOrEqual = 2,
1646
+ NotEqual = 3,
1647
+ GreaterThanOrEqual = 4,
1648
+ GreaterThan = 5,
1649
+ }
1650
+
1651
+ /** Dynamic AutoFilter type, in `ST_DynamicFilterType` schema order. Mirrors `fm_dynamic_filter_type_t`. */
1652
+ export enum DynamicFilterType {
1653
+ Null = 0,
1654
+ AboveAverage = 1,
1655
+ BelowAverage = 2,
1656
+ Tomorrow = 3,
1657
+ Today = 4,
1658
+ Yesterday = 5,
1659
+ NextWeek = 6,
1660
+ ThisWeek = 7,
1661
+ LastWeek = 8,
1662
+ NextMonth = 9,
1663
+ ThisMonth = 10,
1664
+ LastMonth = 11,
1665
+ NextQuarter = 12,
1666
+ ThisQuarter = 13,
1667
+ LastQuarter = 14,
1668
+ NextYear = 15,
1669
+ ThisYear = 16,
1670
+ LastYear = 17,
1671
+ YearToDate = 18,
1672
+ Q1 = 19,
1673
+ Q2 = 20,
1674
+ Q3 = 21,
1675
+ Q4 = 22,
1676
+ M1 = 23,
1677
+ M2 = 24,
1678
+ M3 = 25,
1679
+ M4 = 26,
1680
+ M5 = 27,
1681
+ M6 = 28,
1682
+ M7 = 29,
1683
+ M8 = 30,
1684
+ M9 = 31,
1685
+ M10 = 32,
1686
+ M11 = 33,
1687
+ M12 = 34,
1688
+ }
1689
+
1690
+ /** What a sort condition sorts by. Mirrors `fm_sort_by_t`. */
1691
+ export enum SortBy {
1692
+ Value = 0,
1693
+ CellColor = 1,
1694
+ FontColor = 2,
1695
+ Icon = 3,
1696
+ }
1697
+
1698
+ /** Sort method of an AutoFilter sort state. Mirrors `fm_sort_method_t`. */
1699
+ export enum SortMethod {
1700
+ None = 0,
1701
+ PinYin = 1,
1702
+ Stroke = 2,
1703
+ }
1704
+
1705
+ /** Granularity of an AutoFilter date-group item. Mirrors `fm_date_time_grouping_t`. */
1706
+ export enum DateTimeGrouping {
1707
+ Year = 0,
1708
+ Month = 1,
1709
+ Day = 2,
1710
+ Hour = 3,
1711
+ Minute = 4,
1712
+ Second = 5,
1713
+ }
1714
+
1715
+ /** Data-validation error style. Mirrors `fm_validation_error_style_t`. */
1716
+ export enum ValidationErrorStyle {
1717
+ Stop = 0,
1718
+ Warning = 1,
1719
+ Information = 2,
1720
+ }
1721
+
1722
+ /** Where a colour is used; decides what an automatic colour means. Mirrors `fm_color_context_t`. */
1723
+ export enum ColorContext {
1724
+ Font = 0,
1725
+ FillForeground = 1,
1726
+ FillBackground = 2,
1727
+ Border = 3,
1728
+ }
1729
+
1730
+ /** Raster format of an image; `Unknown` marks "no image bytes found". Mirrors `fm_image_format_t`. */
1731
+ export enum ImageFormat {
1732
+ Unknown = 0,
1733
+ Png = 1,
1734
+ Jpeg = 2,
1735
+ Gif = 3,
1736
+ Bmp = 4,
1737
+ }
1738
+
1739
+ /** What a drawing anchor holds. Mirrors `fm_drawing_object_kind_t`. */
1740
+ export enum DrawingObjectKind {
1741
+ Picture = 0,
1742
+ Shape = 1,
1743
+ Chart = 2,
1744
+ Group = 3,
1745
+ Connector = 4,
1746
+ GraphicFrame = 5,
1747
+ Other = 6,
1748
+ }
1749
+
1750
+ /** The anchor element type of a drawing object. Mirrors `fm_anchor_kind_t`. */
1751
+ export enum AnchorKind {
1752
+ OneCell = 0,
1753
+ TwoCell = 1,
1754
+ Absolute = 2,
1755
+ }
1756
+
1757
+ /** How a drawing object follows row and column edits. Mirrors `fm_anchor_edit_as_t`. */
1758
+ export enum AnchorEditAs {
1759
+ TwoCell = 0,
1760
+ OneCell = 1,
1761
+ Absolute = 2,
1762
+ }
1763
+
1764
+ /** How a colour was resolved. Mirrors `fm_color_resolution_t`. `Exact` is a literal or workbook-supplied
1765
+ * colour; `DefaultTheme` / `ThemeUnparseable` mean the default (Office 2013-2022) theme was used because
1766
+ * the theme part is absent / unparseable; `IndexOutOfRange` is black; `AutoContext` is an automatic colour
1767
+ * (black for font and border, white for fills). */
1768
+ export enum ColorResolution {
1769
+ Exact = 0,
1770
+ DefaultTheme = 1,
1771
+ IndexOutOfRange = 2,
1772
+ ThemeUnparseable = 3,
1773
+ AutoContext = 4,
1774
+ }
1775
+
1776
+ /** Where `getTheme` read the theme from. Mirrors the C `out_source` values. */
1777
+ export enum ThemeSource {
1778
+ Part = 0,
1779
+ Default = 1,
1780
+ Unparseable = 2,
1781
+ }
1782
+
1783
+ /** Where `getEffectiveStyle` took its xf from. */
1784
+ export enum EffectiveStyleSource {
1785
+ Cell = 0,
1786
+ Row = 1,
1787
+ Column = 2,
1788
+ Default = 3,
1789
+ }
1790
+
1791
+ /** The theme's typefaces; `*EastAsian` is the `a:ea` face, else the `Jpan` script face. */
1792
+ export interface ThemeFonts {
1793
+ majorLatin: string;
1794
+ majorEastAsian: string;
1795
+ minorLatin: string;
1796
+ minorEastAsian: string;
1797
+ }
1798
+
1799
+ /** Return type of `Workbook.getTheme()`. */
1800
+ export interface ThemeResult {
1801
+ status: Status;
1802
+ /** One of `ThemeSource.*`. */
1803
+ source: ThemeSource;
1804
+ /** 0xFFRRGGBB in `clrScheme` order: dk1, lt1, dk2, lt2, accent1..6, hlink, folHlink. */
1805
+ colors: number[];
1806
+ fonts: ThemeFonts;
1807
+ }
1808
+
1809
+ /** A resolved colour: 0xFFRRGGBB plus how it was obtained. */
1810
+ export interface ResolvedColor {
1811
+ argb: number;
1812
+ resolution: ColorResolution;
1813
+ }
1814
+
1815
+ /** Return type of `Workbook.resolveColor(...)`. */
1816
+ export interface ResolvedColorResult extends ResolvedColor {
1817
+ status: Status;
1818
+ }
1819
+
1820
+ /** Return type of `Workbook.getEffectiveStyle(...)`. */
1821
+ export interface EffectiveStyleResult {
1822
+ status: Status;
1823
+ xfIndex: number;
1824
+ /** One of `EffectiveStyleSource.*`. */
1825
+ source: EffectiveStyleSource;
1826
+ fontIndex: number;
1827
+ fillIndex: number;
1828
+ borderIndex: number;
1829
+ font: ResolvedColor;
1830
+ fillForeground: ResolvedColor;
1831
+ fillBackground: ResolvedColor;
1832
+ borders: {
1833
+ left: ResolvedColor;
1834
+ right: ResolvedColor;
1835
+ top: ResolvedColor;
1836
+ bottom: ResolvedColor;
1837
+ diagonal: ResolvedColor;
1838
+ };
1839
+ locked: boolean;
1840
+ hidden: boolean;
1841
+ numFmtCode: string;
1424
1842
  }
1425
1843
 
1426
1844
  /** Return type of `Workbook.getCellStyle(index)`. Mirrors
@@ -1492,6 +1910,226 @@ export interface SheetAutoFilterXmlResult {
1492
1910
  xml: string;
1493
1911
  }
1494
1912
 
1913
+ /** One `<dateGroupItem>` of a values filter. `grouping` is the granularity
1914
+ * the item matches at (a `DateTimeGrouping`); fields finer than `grouping` are zero. */
1915
+ export interface AutoFilterDateGroup {
1916
+ year: number;
1917
+ month: number;
1918
+ day: number;
1919
+ hour: number;
1920
+ minute: number;
1921
+ second: number;
1922
+ grouping: DateTimeGrouping;
1923
+ }
1924
+
1925
+ /** One `<filterColumn>`. `colId` is the 0-based offset from the first column
1926
+ * of the AutoFilter range. `kind` selects the criterion and only that
1927
+ * criterion's fields are read on input (a `FilterKind`); on output every other criterion's
1928
+ * fields are zero. Custom operators `op1` / `op2` are
1929
+ * `FilterOperator`s; `dynamicType` is a `DynamicFilterType`.
1930
+ * `dxfId` of `4294967295` means absent. `iconSet` is the conditional-format
1931
+ * icon-set ordinal. Omitted input fields read as zero / false / empty,
1932
+ * except `showButton` (true) and `dxfId` (absent). */
1933
+ export interface AutoFilterColumn {
1934
+ colId: number;
1935
+ hiddenButton: boolean;
1936
+ showButton: boolean;
1937
+ kind: FilterKind;
1938
+ filterBlank: boolean;
1939
+ values: string[];
1940
+ dateGroups: AutoFilterDateGroup[];
1941
+ customAnd: boolean;
1942
+ customCount: number;
1943
+ op1: FilterOperator;
1944
+ val1: string;
1945
+ op2: FilterOperator;
1946
+ val2: string;
1947
+ top: boolean;
1948
+ percent: boolean;
1949
+ hasFilterVal: boolean;
1950
+ topVal: number;
1951
+ filterVal: number;
1952
+ dynamicType: DynamicFilterType;
1953
+ hasDynVal: boolean;
1954
+ hasDynMaxVal: boolean;
1955
+ dynVal: number;
1956
+ dynMaxVal: number;
1957
+ valIso: string;
1958
+ maxValIso: string;
1959
+ dxfId: number;
1960
+ cellColor: boolean;
1961
+ iconSet: number;
1962
+ iconId: number;
1963
+ hasIconId: boolean;
1964
+ }
1965
+
1966
+ /** One `<sortCondition>`. `sortBy` is a `SortBy`. `dxfId` is read only when `hasDxfId`, `iconId` only when
1967
+ * `hasIconId`. */
1968
+ export interface AutoFilterSortCondition {
1969
+ ref: MergeRange;
1970
+ descending: boolean;
1971
+ sortBy: SortBy;
1972
+ customList: string;
1973
+ dxfId: number;
1974
+ hasDxfId: boolean;
1975
+ iconSet: number;
1976
+ iconId: number;
1977
+ hasIconId: boolean;
1978
+ }
1979
+
1980
+ /** The `<sortState>` of an AutoFilter. `sortMethod` is a
1981
+ * `SortMethod`. */
1982
+ export interface AutoFilterSortState {
1983
+ ref: MergeRange;
1984
+ columnSort: boolean;
1985
+ caseSensitive: boolean;
1986
+ sortMethod: SortMethod;
1987
+ conditions: AutoFilterSortCondition[];
1988
+ }
1989
+
1990
+ /** A sheet or table AutoFilter. `range` includes the header row; `columns`
1991
+ * must be in strictly ascending `colId` order inside it. */
1992
+ export interface AutoFilter {
1993
+ range: MergeRange;
1994
+ columns: AutoFilterColumn[];
1995
+ sort: AutoFilterSortState | null;
1996
+ }
1997
+
1998
+ /** Result of `Workbook.getAutoFilter` / `getTableAutoFilter`. `autoFilter` is
1999
+ * `null` when there is none. */
2000
+ export interface AutoFilterResult {
2001
+ status: Status;
2002
+ autoFilter: AutoFilter | null;
2003
+ }
2004
+
2005
+ /** Result of `Workbook.evaluateAutoFilter` / `evaluateTableAutoFilter`.
2006
+ * `match[i]` tells whether body row `firstRow + i` satisfies the criteria. */
2007
+ export interface AutoFilterEvalResult {
2008
+ status: Status;
2009
+ firstRow: number;
2010
+ match: boolean[];
2011
+ }
2012
+
2013
+ /** Result of `Workbook.validateValue`. `hasRule` is false when no rule covers
2014
+ * the cell, and `valid` is then true. Otherwise `ruleIndex` indexes
2015
+ * `getValidations` and `errorStyle` is a `ValidationErrorStyle`. */
2016
+ export interface ValidationOutcomeResult {
2017
+ status: Status;
2018
+ hasRule: boolean;
2019
+ valid: boolean;
2020
+ ruleIndex: number;
2021
+ errorStyle: ValidationErrorStyle;
2022
+ }
2023
+
2024
+ /** One `@person` mention in a threaded comment's text; `start` and `length`
2025
+ * are in UTF-16 code units. */
2026
+ export interface Mention {
2027
+ personId: string;
2028
+ mentionId: string;
2029
+ start: number;
2030
+ length: number;
2031
+ }
2032
+
2033
+ /** One threaded comment: a thread's opening comment, or a reply when
2034
+ * `parentId` is non-empty. Ids are brace-wrapped uppercase GUIDs and
2035
+ * `created` is `YYYY-MM-DDTHH:MM:SS.ss`; the caller supplies both. `done`
2036
+ * is the thread's resolved state, meaningful on the opening comment only. */
2037
+ export interface ThreadedComment {
2038
+ id: string;
2039
+ row: number;
2040
+ col: number;
2041
+ personId: string;
2042
+ created: string;
2043
+ text: string;
2044
+ parentId: string;
2045
+ done: boolean;
2046
+ mentions: Mention[];
2047
+ }
2048
+
2049
+ /** One entry of the workbook's person list. */
2050
+ export interface Person {
2051
+ id: string;
2052
+ displayName: string;
2053
+ userId: string;
2054
+ providerId: string;
2055
+ }
2056
+
2057
+ /** Result of `Workbook.getThreadedComments`, in file order: each thread's
2058
+ * opening comment followed by its replies. */
2059
+ export interface ThreadedCommentsResult {
2060
+ status: Status;
2061
+ comments: ThreadedComment[];
2062
+ }
2063
+
2064
+ /** Result of `Workbook.getPersons`. */
2065
+ export interface PersonsResult {
2066
+ status: Status;
2067
+ persons: Person[];
2068
+ }
2069
+
2070
+ /** Format and pixel size of an image; zeroed when `status` is not ok. */
2071
+ export interface ImageInfoResult {
2072
+ status: Status;
2073
+ format: ImageFormat;
2074
+ pxWidth: number;
2075
+ pxHeight: number;
2076
+ }
2077
+
2078
+ /** Result of `Workbook.getImage`. `bytes` is a copy, empty on failure. */
2079
+ export interface ImageResult extends ImageInfoResult {
2080
+ bytes: Uint8Array;
2081
+ }
2082
+
2083
+ /** One anchored object of a sheet's drawing. An absolute anchor reports its
2084
+ * position from A1 as `fromColOff` (x) and `fromRowOff` (y); `toRow` /
2085
+ * `toCol` and their offsets are zero unless the anchor is two-cell. Offsets
2086
+ * and `cx` / `cy` are in EMU. `imageFormat` is non-zero for a picture whose
2087
+ * media part is present; `mediaPath` is empty for a non-picture. */
2088
+ export interface DrawingObject {
2089
+ objectId: number;
2090
+ kind: DrawingObjectKind;
2091
+ anchorKind: AnchorKind;
2092
+ editAs: AnchorEditAs;
2093
+ fromRow: number;
2094
+ fromCol: number;
2095
+ fromRowOff: number;
2096
+ fromColOff: number;
2097
+ toRow: number;
2098
+ toCol: number;
2099
+ toRowOff: number;
2100
+ toColOff: number;
2101
+ cx: number;
2102
+ cy: number;
2103
+ imageFormat: ImageFormat;
2104
+ name: string;
2105
+ descr: string;
2106
+ mediaPath: string;
2107
+ }
2108
+
2109
+ /** Placement of an inserted image. `anchorKind` is `OneCell` (default) or
2110
+ * `TwoCell`; `editAs` applies to a two-cell anchor only. `row` / `col` is
2111
+ * the 0-based top-left cell and `rowOffEmu` / `colOffEmu` the offset inside
2112
+ * it. A zero `widthEmu` / `heightEmu` means the pixel size times 9525. An
2113
+ * empty `name` becomes `Picture <id>`. */
2114
+ export interface ImageInsertOptions {
2115
+ name?: string;
2116
+ descr?: string;
2117
+ anchorKind?: AnchorKind;
2118
+ editAs?: AnchorEditAs;
2119
+ row?: number;
2120
+ col?: number;
2121
+ rowOffEmu?: number;
2122
+ colOffEmu?: number;
2123
+ widthEmu?: number;
2124
+ heightEmu?: number;
2125
+ }
2126
+
2127
+ /** Result of `Workbook.insertImage`; `objectId` is zero on failure. */
2128
+ export interface InsertImageResult {
2129
+ status: Status;
2130
+ objectId: number;
2131
+ }
2132
+
1495
2133
  /** Result of the five raw print-settings getters. The empty `xml` string
1496
2134
  * means the sheet declares no such element. */
1497
2135
  export interface SheetPrintXmlResult {
@@ -1705,6 +2343,19 @@ export interface Workbook {
1705
2343
 
1706
2344
  getValue(sheet: number, row: number, col: number): CellResult;
1707
2345
 
2346
+ /** The stored A1 formula (leading `=` included), or `formula: null` for a cell that holds none. */
2347
+ getFormula(sheet: number, row: number, col: number): FormulaResult;
2348
+ /** The formula in R1C1 notation relative to the cell, without a leading `=`; `formula: null` when the cell holds none. */
2349
+ getFormulaR1C1(sheet: number, row: number, col: number): FormulaResult;
2350
+ /** One page of the populated cells (formula or non-blank value, spill phantoms included) inside
2351
+ * `range`, row-major. `cursor` is the `nextCursor` of the previous page (omit for the first);
2352
+ * `limit` caps the page (omit or 0 for the maximum, 65536). */
2353
+ getCellsInRange(sheet: number, range: MergeRange, cursor?: number | null, limit?: number | null): CellsInRangeResult;
2354
+ /** The text Excel displays for the cell, from its value and number format under the workbook's date system. */
2355
+ getDisplayText(sheet: number, row: number, col: number): DisplayTextResult;
2356
+ /** Renders `value` (blank, number, boolean, text or error) under the stored-form number format `formatCode`; empty means General. */
2357
+ formatValue(value: Value, formatCode: string): DisplayTextResult;
2358
+
1708
2359
  /** Evaluates `formula` as if entered at `(sheet, row, col)` and returns a
1709
2360
  * single scalar result, without mutating the workbook. Local and
1710
2361
  * cross-sheet references, defined names, and `ROW()` / `COLUMN()` resolve
@@ -1890,6 +2541,65 @@ export interface Workbook {
1890
2541
  /** Replaces the worksheet-level `<autoFilter>` XML fragment; empty clears it. */
1891
2542
  setSheetAutoFilterXml(sheet: number, xml: string): Status;
1892
2543
 
2544
+ /** Reads the sheet's typed AutoFilter; `autoFilter` is `null` when absent. */
2545
+ getAutoFilter(sheet: number): AutoFilterResult;
2546
+ /** Replaces the sheet AutoFilter and its hidden `_xlnm._FilterDatabase`
2547
+ * name. Row visibility is unchanged; call `applyAutoFilter` to hide the
2548
+ * excluded rows. */
2549
+ setAutoFilter(sheet: number, filter: AutoFilter): Status;
2550
+ /** Removes the sheet AutoFilter. Row visibility is unchanged. */
2551
+ removeAutoFilter(sheet: number): Status;
2552
+ /** Hides every body row the criteria exclude and shows the rest, as
2553
+ * Excel's Reapply does. Fails with a not-found status when there is no AutoFilter. */
2554
+ applyAutoFilter(sheet: number): Status;
2555
+ /** Drops every column criterion and shows all body rows. */
2556
+ clearAutoFilter(sheet: number): Status;
2557
+ /** Evaluates the sheet AutoFilter without changing the sheet. */
2558
+ evaluateAutoFilter(sheet: number): AutoFilterEvalResult;
2559
+ /** Table counterparts, addressed by the workbook-wide table index
2560
+ * (`tableAt`). */
2561
+ getTableAutoFilter(table: number): AutoFilterResult;
2562
+ setTableAutoFilter(table: number, filter: AutoFilter): Status;
2563
+ removeTableAutoFilter(table: number): Status;
2564
+ applyTableAutoFilter(table: number): Status;
2565
+ clearTableAutoFilter(table: number): Status;
2566
+ evaluateTableAutoFilter(table: number): AutoFilterEvalResult;
2567
+
2568
+ /** Checks `value` against the validation rule covering `(row, col)` without
2569
+ * storing it. The first rule in `getValidations` order wins on overlap. */
2570
+ validateValue(sheet: number, row: number, col: number, value: Value): ValidationOutcomeResult;
2571
+ /** Enumerates populated cells whose value fails their validation rule, in
2572
+ * row-major order, one page at a time; paging as `getCellsInRange`. */
2573
+ listInvalidCells(sheet: number, cursor?: number | null, limit?: number | null): CellsInRangeResult;
2574
+
2575
+ /** Lists the sheet's threaded comments, replies included. */
2576
+ getThreadedComments(sheet: number): ThreadedCommentsResult;
2577
+ /** Adds a threaded comment. An empty `parentId` opens a new thread at
2578
+ * `row` / `col`; otherwise it replies to that thread. */
2579
+ addThreadedComment(sheet: number, comment: Partial<ThreadedComment> & Pick<ThreadedComment, 'id' | 'text'>): Status;
2580
+ /** Replaces the text and mentions of the comment with `id`. */
2581
+ editThreadedComment(sheet: number, id: string, text: string, mentions: Mention[]): Status;
2582
+ /** Sets the resolved state of the thread opened by `threadId`. */
2583
+ setThreadResolved(sheet: number, threadId: string, done: boolean): Status;
2584
+ /** Removes a comment; removing an opening comment removes its thread. */
2585
+ removeThreadedComment(sheet: number, id: string): Status;
2586
+ /** Lists the workbook's persons. */
2587
+ getPersons(): PersonsResult;
2588
+ addPerson(person: Person): Status;
2589
+ /** Fails while a threaded comment or mention still names the person. */
2590
+ removePerson(id: string): Status;
2591
+
2592
+ /** Sniffs the format and pixel size of PNG, JPEG, GIF or BMP bytes without touching the workbook. */
2593
+ probeImage(bytes: Uint8Array): ImageInfoResult;
2594
+ /** Lists the anchored objects of the sheet's drawing, in document order. */
2595
+ listDrawingObjects(sheet: number): ListResult<DrawingObject>;
2596
+ /** Returns a copy of the media bytes of the picture `objectId`. */
2597
+ getImage(sheet: number, objectId: number): ImageResult;
2598
+ /** Inserts `bytes` as a picture; existing drawing content is kept. */
2599
+ insertImage(sheet: number, bytes: Uint8Array, opts?: ImageInsertOptions): InsertImageResult;
2600
+ /** Removes the picture `objectId` and its media once nothing else references it. */
2601
+ removeImage(sheet: number, objectId: number): Status;
2602
+
1893
2603
  passthroughCount(): NumberResult;
1894
2604
  passthroughAt(idx: number): PassthroughEntry;
1895
2605
 
@@ -2226,6 +2936,27 @@ export interface Workbook {
2226
2936
  setRowHidden(sheet: number, row: number, hidden: boolean): Status;
2227
2937
  /** Sets / replaces the row outline level at `row` (clamped to 0..255). */
2228
2938
  setRowOutline(sheet: number, row: number, level: number): Status;
2939
+ /** Removes the height override at `row`, returning it to the sheet default. */
2940
+ clearRowHeight(sheet: number, row: number): Status;
2941
+
2942
+ /** Reads the sheet's default column / row metrics. */
2943
+ getSheetFormatDefaults(sheet: number): SheetFormatDefaultsResult;
2944
+ /** Replaces the sheet's default column / row metrics. A `has*` flag left out defaults to whether its value was supplied. */
2945
+ setSheetFormatDefaults(sheet: number, defaults: Partial<SheetFormatDefaults>): Status;
2946
+
2947
+ /** Rectangle covering the inclusive cell range, in points from the top-left of A1.
2948
+ * Hidden rows and columns contribute zero extent. */
2949
+ getCellRectPt(sheet: number, range: MergeRange, mode: GeometryMode): CellRectResult;
2950
+ /** Effective column width in points; zero when hidden. */
2951
+ getColumnWidthPt(sheet: number, col: number, mode: GeometryMode): NumberResult;
2952
+ /** Effective row height in points; zero when hidden. */
2953
+ getRowHeightPt(sheet: number, row: number): NumberResult;
2954
+ /** The character-unit to point conversion model for the workbook's Normal font. */
2955
+ getWidthModel(sheet: number, mode: GeometryMode): WidthModelResult;
2956
+ /** Converts a column width in characters to points. */
2957
+ columnCharsToPt(sheet: number, mode: GeometryMode, chars: number): NumberResult;
2958
+ /** Inverse of `columnCharsToPt`; a width at or below the padding maps to zero characters. */
2959
+ columnPtToChars(sheet: number, mode: GeometryMode, pt: number): NumberResult;
2229
2960
 
2230
2961
  /** Returns `{ status, xfIndex }` for the cell at `(sheet, row, col)`. */
2231
2962
  getCellXfIndex(sheet: number, row: number, col: number): CellXfIndexResult;
@@ -2316,10 +3047,30 @@ export interface Workbook {
2316
3047
  * `<cellStyleXfs>` index, which is what `setCellStyle` and
2317
3048
  * `CellXf.xfId` reference. */
2318
3049
  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;
3050
+ /** Adds or replaces the `<cellStyle>` entry named `record.name`. Absent
3051
+ * fields default to `xfId` 0, a custom style (`0xFFFFFFFF`), level 0 and
3052
+ * both flags false. */
3053
+ setCellStyle(record: CellStyleRecord): Status;
3054
+ /** Removes the `<cellStyle>` named `name`; cell formats that used it are
3055
+ * repointed at the Normal style. */
3056
+ removeCellStyle(name: string): Status;
3057
+
3058
+ /** The 12 theme colours (`clrScheme` order) and the theme typefaces. The
3059
+ * default theme is reported when the part is absent or unparseable;
3060
+ * `source` tells the cases apart. */
3061
+ getTheme(): ThemeResult;
3062
+ /** Rewrites the 12 scheme colours (`clrScheme` order, alpha ignored). A
3063
+ * workbook without a theme part first gets a minimal one. */
3064
+ setThemeColors(colors: number[]): Status;
3065
+ /** Rewrites the theme's major and minor typefaces. */
3066
+ setThemeFonts(fonts: ThemeFonts): Status;
3067
+ /** Resolves a colour specification to ARGB against the theme and the
3068
+ * indexed palette; `context` decides what an automatic colour means. */
3069
+ resolveColor(spec: ColorSpec, context: ColorContext): ResolvedColorResult;
3070
+ /** The formatting a cell shows: the xf chosen from cell, row, column or
3071
+ * the default, with its colours resolved. Conditional formatting is not
3072
+ * applied. */
3073
+ getEffectiveStyle(sheet: number, row: number, col: number): EffectiveStyleResult;
2323
3074
 
2324
3075
  /** Returns every external-link record carried by the workbook in
2325
3076
  * `<externalReferences>` document order. Empty for fresh workbooks
@@ -2337,6 +3088,8 @@ export interface Workbook {
2337
3088
  clearMerges(sheet: number): Status;
2338
3089
  /** Returns every merge range on `sheet` as a JS array. */
2339
3090
  getMerges(sheet: number): ListResult<MergeRange>;
3091
+ /** Returns the merge ranges on `sheet` that intersect `range`, in storage order. */
3092
+ getMergesInRange(sheet: number, range: MergeRange): ListResult<MergeRange>;
2340
3093
 
2341
3094
  /** Returns the cell comment at `(sheet, row, col)`, or `null` when absent. */
2342
3095
  getComment(sheet: number, row: number, col: number): CommentEntry | null;