@sheetxl/io-xlsx 0.8.0-beta.12 → 0.8.0-beta.14

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.
Files changed (54) hide show
  1. package/browser/esm/{9dwUocbOsJuAcmKn.mjs → BjkdoGjLpkKUlK5q.mjs} +2234 -2250
  2. package/browser/esm/{DeMZN_qj__PKo4Wh.mjs → Bomb4K5f16UyiyED.mjs} +1 -1
  3. package/browser/esm/{D8k22TSWPd_RHEpj.mjs → Bs0IJqyry5ZycCBU.mjs} +988 -1008
  4. package/browser/esm/CIRY1QIACITHu_lA.mjs +24 -0
  5. package/browser/esm/{DVLJTjJCGqrJUa8c.mjs → Cs4lg7bxClbTkldF.mjs} +61 -61
  6. package/browser/esm/{aUBXbTh2r0u3x4Xo.mjs → DAYdoS9sLmYf8kzD.mjs} +2 -2
  7. package/browser/esm/{BIvDjK4Zl8bWRgl8.mjs → DKWU_JYjVmtOzTGr.mjs} +2 -2
  8. package/browser/esm/{DsppUz-14Z7ti9i3.mjs → DN7ig6HovGU5gMbr.mjs} +1 -1
  9. package/browser/esm/{CcH5ITJFTMVWUJO9.mjs → DbygDdjktfjoU4DI.mjs} +1041 -1041
  10. package/browser/esm/{DO75RoAQTgMuVzXv.mjs → DiNNY0EgHikWbrDz.mjs} +2 -2
  11. package/browser/esm/{DKnOwucZq4z9_-r-.mjs → QuYxg3ec6kN-djPF.mjs} +4 -4
  12. package/browser/esm/index.mjs +2 -2
  13. package/node/esm/{C78E45n6j2E8rruH.mjs → BCSJ_kqVLXkZlYh3.mjs} +818 -819
  14. package/node/esm/{DXusvwW73FUDSyvD.mjs → BCXSNXHvNQ9JQMLE.mjs} +1129 -1129
  15. package/node/esm/{DsyuWxk3bdGhJUQN.mjs → BycDf9HTtfpzL-zt.mjs} +1 -1
  16. package/node/esm/{BmIIQODk4dBVIXA4.mjs → CTdvEKRTM-W1L1KU.mjs} +976 -994
  17. package/node/esm/{DCaAOfuW-w_dx_qd.mjs → CkenuXqno-ffP331.mjs} +2 -2
  18. package/node/esm/{CDKm5s3JE_d99TJw.mjs → CvcAx132Yp5uUDUB.mjs} +81 -81
  19. package/node/esm/{C-e5AO_4TnGywT-m.mjs → H9egT6kWCw8RAf76.mjs} +1 -1
  20. package/node/esm/{DSgxL0sBZtWMydVl.mjs → TPq4Re0SQgONsX_u.mjs} +2 -2
  21. package/node/esm/index.mjs +4 -4
  22. package/package.json +3 -3
  23. package/types/src/AutoFilterRules.d.ts +0 -42
  24. package/types/src/DataTableFormula.d.ts +0 -10
  25. package/types/src/DataValidationRules.d.ts +0 -5
  26. package/types/src/ExcelCalcStamp.d.ts +0 -36
  27. package/types/src/ExcelCompat.d.ts +0 -140
  28. package/types/src/ExcelFunctionFacts.d.ts +0 -272
  29. package/types/src/ExcelReservedNames.d.ts +0 -64
  30. package/types/src/KnownFonts.d.ts +0 -13
  31. package/types/src/LegacyFormula.d.ts +0 -58
  32. package/types/src/Plugin.d.ts +3 -3
  33. package/types/src/SheetKinds.d.ts +0 -15
  34. package/types/src/SourcePackage.d.ts +0 -44
  35. package/types/src/Types.d.ts +2 -3
  36. package/types/src/chart/_chartExStyle.d.ts +0 -9
  37. package/types/src/reader/DummyFunctionUnwrap.d.ts +43 -23
  38. package/types/src/reader/domVisitors/AutoFilterVisitor.d.ts +0 -8
  39. package/types/src/reader/domVisitors/ExternalLinkVisitor.d.ts +0 -10
  40. package/types/src/reader/domVisitors/FeaturePropertyBagVisitor.d.ts +0 -9
  41. package/types/src/reader/domVisitors/FmtSchemeVisitor.d.ts +0 -11
  42. package/types/src/reader/domVisitors/WorkbookVisitor.d.ts +0 -9
  43. package/types/src/reader/saxVisitors/SharedStringsVisitor.d.ts +0 -15
  44. package/types/src/reader/saxVisitors/WorksheetVisitor.d.ts +3 -1
  45. package/types/src/richValue/WebImageRichValueHandler.d.ts +0 -5
  46. package/types/src/utils/VmlNoteStyle.d.ts +0 -19
  47. package/types/src/vba/VBAProject.d.ts +0 -19
  48. package/types/src/writer/builder/OpcXmlUtils.d.ts +0 -8
  49. package/types/src/writer/builder/PackageBuilder.d.ts +0 -41
  50. package/types/src/writer/builder/Types.d.ts +0 -30
  51. package/types/src/writer/emitters/ExternalLinkEmitter.d.ts +0 -11
  52. package/types/src/writer/emitters/FeaturePropertyBagEmitter.d.ts +0 -10
  53. package/types/src/writer/utils/DefaultRows.d.ts +0 -16
  54. package/types/src/writer/utils/DummyFunction.d.ts +0 -23
@@ -10,39 +10,6 @@ export declare const DYNAMIC_FILTER_PERIODS: ReadonlySet<string>;
10
10
  * cache of its last evaluation, never read.
11
11
  */
12
12
  export declare function dynamicFilterToJSON(type: string | null | undefined): ICondition.JSON;
13
- /**
14
- * The border between OOXML's `customFilter` and the SDK's condition.
15
- *
16
- * @remarks
17
- * `customFilter` is the third of OOXML's three condition systems, and the only one that had no
18
- * border of its own: the reader passed `@operator` straight through as an SDK operator name and
19
- * the writer switched SDK names against OOXML spellings. The two vocabularies overlap on exactly
20
- * `lessThan` and `greaterThan`, so those worked and the other four did not — `greaterThanOrEqual`
21
- * arrived as an operator no registry knew, and left again as `equal`.
22
- *
23
- * Both directions live in one file, as they do for data validations and conditional formats: they
24
- * are one table, and a mapping whose halves drift apart is the bug the round-trip corpus exists to
25
- * catch.
26
- *
27
- * Excel has no text operators here. Its text filters are `equal` / `notEqual` over a pattern packed
28
- * into `@val`: `abc*` begins with, `*abc` ends with, `*abc*` contains, and `~` before `*`, `?` or
29
- * `~` makes that character literal. The three shapes map onto the SDK's text operators; any other
30
- * pattern (`a*b`, `a?c`) has no operator and is carried under its OOXML spelling, inert, so a resave
31
- * writes it back as it arrived.
32
- *
33
- * A wildcard-free `equal` compares the text a cell shows (P1, P5, P10): it reads as `equalTo`
34
- * under the Display selector ("displays as") and `notEqual` as its negation; `equalTo` under no
35
- * selector is value equality and never comes from here (DESIGN-FILTER §3.2, MODEL-CONDITIONS §4).
36
- * Excel stores a plain `equal` as `<filters><filter val>` on save, and so does this writer, which
37
- * is why it reopens as a one-item `inSet` under Display; the two are the same predicate. Excel's
38
- * `<>` criterion is `notEqual` against one space (P7) and reads as `not(blank)` under Display,
39
- * since a string of spaces is blank to it (§3.3). The selector sits on the leaf that reads the
40
- * value: inside a `not`, on each child of a pair.
41
- *
42
- * Value equality has no `customFilter` spelling. A value `EqualTo` on a number goes out as Excel's
43
- * own value test, `<customFilters and="1">` of `greaterThanOrEqual` and `lessThanOrEqual` with
44
- * the same operand, which Excel evaluates live; {@link foldComparisonPair} reads it back.
45
- */
46
13
  /** A `customFilter` in OOXML's own shape. Reader input, writer output — never persisted. */
47
14
  export interface OOXMLCustomFilter {
48
15
  operator?: string | null;
@@ -81,15 +48,6 @@ export declare function escapeWildcards(text: string): string;
81
48
  * not read through here — they are a one-item values list, whose item is text.
82
49
  */
83
50
  export declare function valToParam(val: string | null | undefined): string | number | undefined;
84
- /**
85
- * A param or a values-list item as the text an attribute holds.
86
- *
87
- * @remarks
88
- * A typed value is written as `String(value)`, which is the text it shows only under `General`. A
89
- * value list (`inSet` under no selector) written this way reopens as a display list and keeps a
90
- * number under `0.00` only if it shows as `1.5`; the writer warns. (PLAN-FILTER Phase 4 spells a
91
- * value list as the texts the value shows in its column.)
92
- */
93
51
  export declare function paramToVal(param: unknown): string | undefined;
94
52
  /**
95
53
  * Reads a `customFilter` as a condition.
@@ -1,9 +1,4 @@
1
1
  import { IRange } from '@sheetxl/sdk';
2
- /**
3
- * A what-if data table as a file states one: what Excel's `<f t="dataTable">` and LibreOffice's
4
- * per-cell `TABLE(...)` both describe, and what `TABLE(rowInput, columnInput, rows, columns)` at the
5
- * results' top-left says in the model (DESIGN-DATA-TABLES §4.5).
6
- */
7
2
  export interface DataTableDefinition {
8
3
  /** The result cells. */
9
4
  ref: IRange.Coords;
@@ -27,10 +22,5 @@ export declare const toDataTableFormula: (table: DataTableDefinition) => string;
27
22
  * @param anchor The cell the formula sits in: the results' top-left.
28
23
  */
29
24
  export declare const parseDataTableFormula: (text: string, anchor: IRange.CellCoords) => DataTableDefinition | null;
30
- /**
31
- * Excel's `<f t="dataTable">` attributes for a definition, in Excel's order. `r1` is the row input
32
- * of a two-input table, else the one input, with `dtr` saying which; Excel writes `dt2D` and `dtr`
33
- * both ways. A deleted input is `del1`/`del2` with no address (probe P8, PLAN-DATA-TABLES §0b).
34
- */
35
25
  export declare const dataTableAttributes: (table: DataTableDefinition) => Record<string, string>;
36
26
  //# sourceMappingURL=DataTableFormula.d.ts.map
@@ -43,11 +43,6 @@ export type DvType = typeof DvType[keyof typeof DvType];
43
43
  * `$A$1:$A$5` are formula text by type, carried verbatim with no marker.
44
44
  */
45
45
  export declare function formulaToParam(text: string, type: string | undefined): Scalar;
46
- /**
47
- * The most characters Excel reads from a `dataValidation`'s `prompt`, `error`, `promptTitle` or
48
- * `errorTitle`. One more and Excel refuses to open the workbook at all (probe P5). Excel's own
49
- * authoring stops sooner (titles 32, prompt 254, error 225); the file is what matters here.
50
- */
51
46
  export declare const MAX_MESSAGE_LENGTH = 255;
52
47
  /**
53
48
  * `text` cut to {@link MAX_MESSAGE_LENGTH}, never splitting a surrogate pair; `warn` names the
@@ -1,39 +1,3 @@
1
- /**
2
- * The Excel calculation-engine stamp this package is verified against.
3
- *
4
- * @remarks
5
- * The writer stamps a workbook that has no source of its own with these, and the reader's
6
- * calc-on-load policy compares a file's `calcId` against the same build. Raise the two together,
7
- * and only alongside the oracle they name.
8
- */
9
- /**
10
- * The `calcPr@calcId` of the Excel build this engine's results are verified against.
11
- *
12
- * @remarks
13
- * `calcId` is the version of the Excel calculation engine that last calculated a file. On open,
14
- * Excel trusts the stored values when the id is its own or newer and performs a FULL
15
- * recalculation when it is older or absent — which turns every citation of a closed external
16
- * book into `#REF!` (DESIGN-EXTERNAL-LINKS phase D). So a written workbook is stamped with the id
17
- * of the build this engine's results are verified against — the COM oracle, Excel 16.0, which
18
- * writes `191029` (`externalLinksNames.xlsx`, authored by it 2026-09-11) — and a source file's own
19
- * id is carried through unchanged, so a resave keeps exactly the trust the original had. A later
20
- * Excel, whose id is higher, recalculates on open as it does for its own older files.
21
- *
22
- * On read, a file whose id is absent or below this one is recalculated as Excel would.
23
- */
24
1
  export declare const EXCEL_CALC_ID_VERIFIED = "191029";
25
- /**
26
- * The `xcalcf:calcFeatures` extension written for a workbook that has no source list of its own —
27
- * the other half of the trust {@link EXCEL_CALC_ID_VERIFIED} buys.
28
- *
29
- * @remarks
30
- * Since 2018 Excel also records which calculation FEATURES the engine that last calculated the
31
- * file had (`microsoft.com:RD`, `Single`, `LET_WF`, …), and recalculates a file on open whose
32
- * list lacks any of its own — measured 2026-09-11 through the COM oracle: Excel's own resave of
33
- * `externalLinksNames.xlsx` opens with its stored values, and the same file with ONLY this
34
- * extension removed opens recalculated (`#REF!`, `#NAME?`), while removing `calcChain.xml` or
35
- * spelling a legacy cell `_xlfn.SINGLE(...)` changes nothing. The list is the one that Excel
36
- * build writes; a source file's own is carried through unchanged.
37
- */
38
2
  export declare const EXCEL_CALC_FEATURES_VERIFIED: string;
39
3
  //# sourceMappingURL=ExcelCalcStamp.d.ts.map
@@ -1,74 +1,8 @@
1
1
  import { IFunction, IRange, INamed, IWorksheet, ICalculation } from '@sheetxl/sdk';
2
- /**
3
- * The implicit-intersection translation between the modern (dynamic) formula model and what a
4
- * legacy xlsx `<f>` means — item 47's `ExcelCompat.ts`, born in io-xlsx
5
- * (DESIGN-FORMULA-DIALECT.md §3).
6
- *
7
- * Both directions live here, built on ONE site rule so they cannot drift (FORMULA-SEMANTICS §6.1
8
- * — after the read transform a divergence is a wrong VALUE, not non-canonical XML):
9
- *
10
- * - READ (rules 1/2): a plain `<f>` — no `t="array"`, no `cm` — has legacy semantics whatever its
11
- * age, and loading it means putting the `@` back where Excel would
12
- * (`=ABS(A1:A5)` → `=ABS(@A1:A5)`). The decision is per CELL, and the bit rides BESIDE the
13
- * formula exactly as it does on disk, never inside it: `cm=`/`t="array"` are cell attributes,
14
- * the reader records their extents in `sheet.formulaArray`, and the load asks per formula which
15
- * of {@link createCompatReadTransforms}' two transforms to run
16
- * (`ICalculation.FormulaTransformContext`).
17
- * - WRITE: the `cm="1"` + `t="array"` marker goes on every formula legacy intersection would
18
- * change — {@link hasIntersectionSite}, answered beside the formula by the dialect's `annotate`
19
- * ({@link registerXlsxFormulaDialect}) and read by `WorksheetEmitter`. On a formula written
20
- * PLAIN, an `@` the legacy read would put back is not spelled at all — Excel elides it and
21
- * spells `_xlfn.SINGLE` only where the read would not re-insert it
22
- * ({@link createCompatWriteTransform}).
23
- *
24
- * ### An unknown function is a range
25
- *
26
- * A call to a function Excel does not know (an add-in or user-defined function — `CASCADESPARKLINE`
27
- * from SpreadJS, `FOO`) has an unknown return, and Excel treats that as range-VALUED: the call
28
- * takes an `@` at the root and at every scalar site holding it, never on its own arguments, and
29
- * never inside a range-accepting slot. Measured `probe-unknown-function-intersect.ps1`
30
- * (2026-09-03): `=FOO(1)` opens as `=@FOO(1)`, `=ABS(FOO(1))` as `=ABS(@FOO(1))`,
31
- * `=IF(TRUE,FOO(1),2)` as `=@IF(TRUE,FOO(1),2)`, `=FOO(A1:A5)` as `=@FOO(A1:A5)`, while
32
- * `=SUM(FOO(1))`, `=SUMPRODUCT(FOO(A1:A5))` and `=N(FOO(1))` stay plain. The value is `#NAME?`
33
- * either way — what the rule decides is whether the file round-trips to the same TEXT, which
34
- * matters the day the function exists (the same file opened by the application that wrote it).
35
- *
36
- * ### Two kinds of arrayness, and only one of them is a site
37
- *
38
- * Being an array is not the same question as being intersected. Arrayness that comes from a
39
- * REFERENCE — a range, a spill anchor, a table reference, a defined name, an array-returning or
40
- * `valueReturn` call — is a site wherever a value-typed slot holds it, whatever encloses it.
41
- * Arrayness that comes from an inline array CONSTANT is not: legacy Excel LIFTS `{…}` and only
42
- * collapses it where one value is genuinely wanted, which is the cell root and whatever the root's
43
- * demand reaches through ({@link _childDemand}). That is the split `constants` carries through
44
- * {@link _isRangeValued}.
45
- *
46
- * Measured on plain-`<f>` opens, `probe-array-constant-intersection{,2}.ps1` (40 rows, 2026-08-17):
47
- * `={1,2,3}` opens as `=@{1,2,3}` and `=ABS({-1,-2,-3})` as `=ABS(@{-1,-2,-3})`, while
48
- * `=SUM(ABS({-1,-2,-3}))` opens UNTOUCHED at 6 — where the same shape over a range,
49
- * `=SUM(ABS(H1:H3))`, opens as `=SUM(ABS(@H1:H3))`. A name is reference-derived even when its body
50
- * is a constant, which is the pair that kills the simpler reading: `=SUM(ArrConst&0)` opens as
51
- * `=SUM(@ArrConst&0)` = 10 against `=SUM({1,2,3}&0)` = 0.
52
- *
53
- * ### Everything measured; facts OVERRIDE declarations
54
- *
55
- * Every per-function fact the rules below consult lives in the measured `ExcelFunctionFacts` map
56
- * (one row per name, probe provenance and slot addressing documented there). The registry's
57
- * declarations state what a BODY needs and serve as the DEFAULT; wherever Excel measurably
58
- * disagrees, the fact wins (CALC-ISSUES item 44: "use the measured list, not a derived
59
- * predicate"). Re-run the probes when adding a function — no test can detect a new function Excel
60
- * happens to disagree with.
61
- */
62
2
  /** Does any call in this tree name a function on Excel's volatile list
63
3
  * (`ExcelFunctionFact.volatile`)? (Defined-name bodies are not chased: Excel's `ca` reflects the
64
4
  * CELL's own formula text.) */
65
5
  export declare const hasVolatileCall: (root: ICalculation.FormulaNode | undefined) => boolean;
66
- /**
67
- * Does this tree call a function the registry does not know? An unknown call is what Excel's
68
- * `ca="1"` records on a cell that reached a user-defined function during its last calculation
69
- * (measured on every `FOO` cell of `probe-unknown-function-intersect.ps1`) — static here where
70
- * Excel's is a runtime fact, so a call on an untaken lazy branch is flagged too.
71
- */
72
6
  export declare const hasUnknownCall: (root: ICalculation.FormulaNode | undefined, ctx: CompatContext) => boolean;
73
7
  /** What the walks read of a function: its declared slots and return, and whether it is a built-in. */
74
8
  export interface CompatFunction {
@@ -110,31 +44,6 @@ export interface CompatContext {
110
44
  * every rule above traces to Excel's own insertion, not our reading of it.
111
45
  */
112
46
  export declare const insertImplicitIntersection: (root: ICalculation.FormulaNode, ctx: CompatContext) => ICalculation.FormulaNode;
113
- /**
114
- * The WRITE decision — whether legacy implicit intersection would change this formula's meaning,
115
- * which is the exact condition under which Excel writes `cm="1"` + `t="array"`.
116
- *
117
- * @remarks
118
- * A STATIC property of the formula, not the value: `=IF(FALSE,H1:H3,5)` computes `5` and is still
119
- * marked. The same rule as {@link insertImplicitIntersection} by construction: a formula is
120
- * marked exactly when the insertion would change it — plus one clause the insertion rule does not
121
- * share: a `call` node ANYWHERE marks, because immediate application does not exist in the legacy
122
- * dialect at all. Measured (`probe-lambda-call.xlsx`, every accepted case): Excel puts
123
- * `cm="1"` + `t="array"` on `SUM(LAMBDA(x,x+1)(3),1)` (call in an argument slot, scalar root),
124
- * `MyLam(3)`, `A1(3)`, `-LAMBDA(x,-x)(1)`, the curried and partial forms — all of them. Without
125
- * the marker Excel reads the cell back as a LEGACY formula and re-inserts `@` at the root and on
126
- * the lambda parameters (`=@LAMBDA(a,b,@a+@b)(1,2)`), which is exactly what the Excel-open gate
127
- * caught (verify-lambda-call-opens.ps1, 2026-08-13).
128
- *
129
- * "Marked exactly when the insertion would change it" is OUR rule, and Excel's marker is not
130
- * only that — measured `probe-sumproduct-monthyear.ps1` + `probe-slot-class-intersect2.ps1`
131
- * (2026-08-14): the same text entered through legacy `.Formula` saves PLAIN and through modern
132
- * `.Formula2` saves `cm="1" t="array"`, at identical values, on every array-scope shape here. So
133
- * Excel's marker also records the ENTRY CHANNEL, which we do not persist. We write the legacy
134
- * channel's answer, which is the self-consistent one: the file we emit reads back — by Excel and
135
- * by us — to the tree we emitted it from. Carrying a read-side "was marked" bit instead is the
136
- * open alternative.
137
- */
138
47
  export declare const hasIntersectionSite: (root: ICalculation.FormulaNode, ctx: CompatContext) => boolean;
139
48
  /** The reader's two READ transforms — see {@link createCompatReadTransforms}. */
140
49
  export interface CompatReadTransforms {
@@ -178,29 +87,6 @@ export interface XlsxFormulaAnnotation {
178
87
  }
179
88
  /** Where a save's emitters find the workbook's dialect (`EmitContext.getSharedStates`). */
180
89
  export declare const SHARED_STATE_XLSX_FORMULA_DIALECT = "xlsxFormulaDialect";
181
- /**
182
- * The xlsx formula dialect for one workbook: how this format spells formulas, applied to formula
183
- * TEXT, with no calculation involved (DESIGN-CALC-SERVICE §9).
184
- *
185
- * - READ: the on-disk legacy spellings (`_xlfn.`, `_xlws.`, `_xleta.`, `_xlpm.`, `SINGLE`,
186
- * `ANCHORARRAY`, `_TRO_*`, `_LONGTEXT`) unwrapped, and for a plain cell the implicit-intersection
187
- * `@` operators Excel would show, exactly where it would ({@link CompatReadTransforms.legacy});
188
- * an array anchor and a detached formula take the unwrap alone.
189
- * - WRITE: the legacy spellings on every formula, plus, for a plain cell, the elision of each `@`
190
- * the read would put back ({@link createCompatWriteTransform}).
191
- * - ANNOTATE: an {@link XlsxFormulaAnnotation}.
192
- *
193
- * Functions are answered from the built-in declarations, defined names from the workbook's names
194
- * as text; neither needs an engine.
195
- *
196
- * A DETACHED formula is one with no cell of its own: a defined name, a conditional format or data
197
- * validation operand, a cfvo value. Excel evaluates a condition body in CSE mode (nothing
198
- * intersects, measured `probe-cf-intersect.ps1`) and writes it plain with no `cm=`, so the
199
- * plain-cell `@` insertion and elision never apply to it — only the spelling does. That spelling
200
- * needs no names, so a dialect built with none ({@link createXlsxFormulaDialect}) answers
201
- * {@link readDetached} completely; it is what the reader hands the worksheet visitors before the
202
- * workbook's names have been read.
203
- */
204
90
  export interface XlsxFormulaDialect {
205
91
  /**
206
92
  * The tree of the model's canonical text written at `anchor`, in the shape the compiled tree
@@ -279,31 +165,5 @@ export declare function readSheetFormulas(sheet: IWorksheet.JSON, dialect: XlsxF
279
165
  * takes no insertion on read, so every `@` on it has to be explicit.
280
166
  */
281
167
  export declare const impliedIntersections: (root: ICalculation.FormulaNode, ctx: CompatContext) => Set<ICalculation.FormulaNode>;
282
- /**
283
- * The writer's complete WRITE transform for a CELL formula: the legacy spelling on every node
284
- * (`createLegacyWriteTransform`), plus — at the root of a formula that will be written plain —
285
- * the elision of every `@` the legacy read would put back.
286
- *
287
- * @remarks
288
- * Excel's own spelling of a modern `@`, measured `probe-at-elision.ps1` (2026-09-03): `=@A1:A5`
289
- * saves as `A1:A5`, `=ABS(@A1:A5)` as `ABS(A1:A5)`, `=@FOO(1)` as `FOO(1)`, `=@SEQUENCE(5)` as
290
- * `_xlfn.SEQUENCE(5)`; `_xlfn.SINGLE` appears only where the read would NOT re-insert —
291
- * `SUM(_xlfn.SINGLE(A1:A5))`, `SUMPRODUCT(ABS(_xlfn.SINGLE(A1:A5)))`, `_xlfn.SINGLE(SUM(1))`,
292
- * `_xlfn.SINGLE((A1:A5))`. A formula that still has a site after its `@`s are honored is a
293
- * MARKED cell (`cm="1"`) and keeps every `@` explicit (`=@ABS(A1:A5)` →
294
- * `_xlfn.SINGLE(ABS(A1:A5))` under `cm="1"`), because no insertion runs on it. The text is
295
- * therefore self-consistent in both readers: what comes back is the tree that went out.
296
- *
297
- * This is why the SpreadJS/add-in round trip closes: `=@CASCADESPARKLINE(...)` — the modern
298
- * form of the plain `<f>` the authoring application wrote — goes back out as that same plain
299
- * `<f>`, which is the only spelling the authoring application knows.
300
- *
301
- * Mechanics: the spelling runs in the SDK's own post-order walk (fresh nodes keep their trivia
302
- * that way), so by the root every `@` is already a `SINGLE` call. The root pass unwraps a VIEW of
303
- * the spelled tree to ask the modern-tree questions, maps each implied `@` of the view back to
304
- * the `SINGLE` node it came from, and drops those nodes copy-on-write — every untouched node
305
- * keeps its identity, and its whitespace. Defined names and array-anchored cells take the
306
- * spelling pass only (`WorkbookEmitter`'s write provider decides per block; names never run this).
307
- */
308
168
  export declare function createCompatWriteTransform(legacy: ICalculation.FormulaTransform, ctx: CompatContext): ICalculation.FormulaTransform;
309
169
  //# sourceMappingURL=ExcelCompat.d.ts.map
@@ -1,41 +1,3 @@
1
- /**
2
- * Every per-function Excel fact this package holds, in ONE map keyed by the upper-cased function
3
- * name — the single place to see everything measured about a function. The spelling dialect
4
- * (`LegacyFormula.ts`) and the implicit-intersection semantics (`ExcelCompat.ts`) both read it
5
- * through the narrow accessors at the bottom; call sites keep asking concern-specific questions
6
- * and never reach into rows.
7
- *
8
- * ### Everything measured; rows OVERRIDE declarations
9
- *
10
- * Every fact below is a MEASURED Excel fact, probe-regenerable from
11
- * `spreadsheetbench/formula-tests/` (`probe-param-intersect{,2,3}.ps1` — 1,212 parameter slots
12
- * over 497 functions through COM `.Formula`/`.Formula2`; `probe-return-arrayness{,2,3}.ps1` — 508
13
- * returns; `probe-intersect-oracle.ps1` — the 89-row site battery; `probe-slot-class-intersect*.ps1`
14
- * — the array scope; `probe-xlfn-prefixes.ps1` / `probe-excel-knows-name.ps1` — the spellings;
15
- * `probe-volatile-ca.ps1` — `ca="1"`). The registry's declarations state what a BODY needs and
16
- * serve as the DEFAULT; wherever Excel measurably disagrees, the row here wins (CALC-ISSUES item
17
- * 44: "use the measured list, not a derived predicate"). Re-run the probes when adding a function
18
- * — no test can detect a new function Excel happens to disagree with.
19
- * `scripts/excel-function-facts-lint.mjs` joins the committed probe json against this map and
20
- * fails on disagreement, which is what lets the rows stay hand-authored.
21
- *
22
- * ### Absence keeps its meaning, per FIELD
23
- *
24
- * Each field carries its own default for a row that does not declare it (spelled out on the
25
- * field), and those defaults are NOT the same: absent `prefix` means "written bare", absent
26
- * `arrayScope` means "INHERITS the enclosing scope". Getting a default wrong here is silent and
27
- * produces wrong numbers, not errors. The one fact a row's EXISTENCE itself carries: every name
28
- * here is an Excel-side name, and — unless flagged {@link ExcelFunctionFact.unimplemented} — an
29
- * Excel built-in our registry implements, i.e. `_xleta.`-eligible.
30
- *
31
- * ### Slot addressing
32
- *
33
- * Slot fields key parameter positions by the FLATTENED declaration-slot index: the fixed (prefix)
34
- * parameters in order, then the slots of the repeating cycle. `SUMIFS(sumRange, [criteriaRange,
35
- * criteria]…)` is slots 0/1/2 and argument `i ≥ 1` binds to slot `1 + (i − 1) % 2` — every
36
- * criteria pair answers like the first, and insertion stays per-ARGUMENT (two ranges on one slot
37
- * get two `@`, measured F1/F3 of `probe-collecting-slot.ps1`).
38
- */
39
1
  /** Future-function prefix. */
40
2
  export declare const XLFN = "_xlfn.";
41
3
  /**
@@ -49,101 +11,8 @@ export declare const XLWS = "_xlfn._xlws.";
49
11
  * see each field for what its absence means.
50
12
  */
51
13
  export interface ExcelFunctionFact {
52
- /**
53
- * The row exists only for its on-disk SPELLING — our registry implements no function of this
54
- * name, so a bare token can only be a defined-name reference and never takes `_xleta.`. Three
55
- * kinds of member, and only the first is a backlog:
56
- *
57
- * 1. Excel-side functions we do not YET implement — each a candidate, as `ECMA.CEILING` was
58
- * until it graduated (2026-08-15) and the flag came off.
59
- * 2. Documented spellings for surfaces that are not worksheet functions we would ever
60
- * implement: `COPILOT`, `PY` and the `PYTHON_*` trio, `PQSOURCE`, `QUERYSTRING`, `LONGTEXT`.
61
- * These are in the map because MS-XLSX documents the marker (see {@link prefix}) and a file
62
- * carrying one must round-trip; the flag is what stops the ROW — which has to exist for the
63
- * spelling — from also claiming we implement it. Nothing here will ever graduate.
64
- * 3. The operator wrapper spellings only this package writes.
65
- *
66
- * ABSENT (on a row): the name is an Excel built-in our registry implements, and a bare
67
- * (parenthesis-less) use of it writes `_xleta.` — the eta-reduction bit. MEASURED, not derived
68
- * (DESIGN-FORMULA-DIALECT.md: "Excel prefixes what EXCEL considers built-in", not what our
69
- * registry does — a SheetXL-only built-in stays bare, which round-trips more honestly than
70
- * `_xleta.OURFN`; those names have NO row at all). Membership was seeded from the audit-1
71
- * registry dump (`spreadsheetbench/formula-tests/sheetxl-function-names.json`) filtered by the
72
- * measured Excel-knows oracle (`probe-excel-knows-name{,2,3}.ps1/.json`, Excel 16.0: enter
73
- * `=NAME()`; an arity refusal or any non-`#NAME?` value proves Excel has it). Slot behavioral
74
- * verified by `probe-xleta.ps1` / `probe-xleta-lambda-slots.ps1`. Round 3 of the oracle
75
- * (2026-08-15, build 20228) covered this flag's own members: `ECMA.CEILING`/`PQSOURCE`/
76
- * `SINGLE`/`ANCHORARRAY` are known; `LONGTEXT`/`PYTHON_*`/`QUERYSTRING` answer a plain
77
- * `#NAME?` (feature-gated — a negative is build-relative). `COPILOT`/`PY` hang COM entry on
78
- * their connected-experience init and can never go in an automated sweep, but typing them by
79
- * hand answers both: `COPILOT` is `#NAME?` like the rest, while `PY` resolves and refuses on
80
- * ENTITLEMENT (a subscription-tier prompt, not name resolution) — so `PY` is a name this build
81
- * HAS, and only its license is missing.
82
- *
83
- * The one distinction the bit cannot carry — a user-defined name that SHADOWS a built-in
84
- * spelling stays bare — is derived from the workbook's defined-names collection by the caller
85
- * (see `createLegacyWriteTransform`).
86
- */
87
14
  unimplemented?: true;
88
- /**
89
- * The on-disk prefix ({@link XLFN} or {@link XLWS}) — functions added in Excel 2010+ that need
90
- * the marker for backward compatibility, plus the operator spellings only this package writes.
91
- *
92
- * ABSENT: the name is written bare. Excel then reads a bare FUTURE name as a call to a defined
93
- * name that does not exist — `#NAME?`, for a function Excel actually has.
94
- *
95
- * ### Two authorities, and which one wins
96
- *
97
- * A prefixed row is here because a probe MEASURED the spelling, or because MS-XLSX §2.2.2
98
- * DOCUMENTS it — `future-function-list` / `worksheet-only-function-list`, at
99
- * {@link https://learn.microsoft.com/en-us/openspecs/office_standards/ms-xlsx/3d025add-118d-4413-9856-ab65712ec1b0}.
100
- *
101
- * The documented list is taken WHOLE, all of it or none of it: all 155 names it spells have a
102
- * row (joined 2026-08-15), and the 143 inside its `_xlfn.` group plus the 3 `_xlws.` names all
103
- * carry the marker — the 9 outside the group are the split measured below. A documented
104
- * spelling we omit is not a missing feature, it is a formula we silently rewrite into `#NAME?`
105
- * on save, so the bar for a ROW is "Excel writes this name", never "we implement it" — the
106
- * ones we do not implement are marked {@link unimplemented} and carry the spelling alone.
107
- *
108
- * What the list cannot reach is why measurement exists beside it. It omits `TEXTJOIN`,
109
- * `CONCAT`, `IFS`, `SWITCH`, `MAXIFS`, `MINIFS`, `XMATCH` and `ENCODEURL` — 2016/2019-era
110
- * functions Excel really does prefix, and precisely the roster `probe-xlfn-prefixes.ps1` was
111
- * pointed at — plus everything shipped since (`GROUPBY`, `PIVOTBY`, `REGEX*`, `TRIMRANGE`,
112
- * `PERCENTOF`, and the connected text pair `TRANSLATE`/`DETECTLANGUAGE`, measured in round 3
113
- * after both sat here BARE — the spelling nothing in the five joins had ever covered).
114
- * Measurement OVERRIDES the document: the probe enters the formula via
115
- * `Formula2`, saves, and reads the raw `<f>` back, separating "Excel has it and prefixes it"
116
- * from "this build never heard of it" by also recording the VALUE — an unknown name is `#NAME?`
117
- * and nothing else is, and a build that lacks a name still writes `_xlfn.` on it.
118
- *
119
- * ### The nine outside the group — measured, and it SPLITS
120
- *
121
- * The grammar closes its `("_xlfn." (…))` group before `ECMA.CEILING` / `ISO.CEILING` /
122
- * `NETWORKDAYS.INTL` / `WORKDAY.INTL` / `FORECAST.LINEAR` / the `FORECAST.ETS*` trio /
123
- * `FORECAST.ETS.STAT`, and `future-function-call` on the same page is spelled the same way —
124
- * read literally, all nine are written BARE. Round 2 (`probe-xlfn-prefixes2.ps1/.json`,
125
- * 2026-08-15, build 20228) measured them and Excel does BOTH: the four ceiling/workday names
126
- * really are bare, and all five `FORECAST.*` really do take `_xlfn.`. So no reading of the
127
- * grouping was ever going to be right, and the four bare rows were wrong here from the 2026-02
128
- * transcription until this measurement — we had been writing `_xlfn.NETWORKDAYS.INTL` for a
129
- * name Excel writes plain. (Only the WRITE direction moved: the reader strips every leading
130
- * marker unconditionally, so files carrying the old spelling still load.)
131
- */
132
15
  prefix?: string;
133
- /**
134
- * `'never'`: Excel NEVER intersects into this function, at any argument — the item-44 origin
135
- * term.
136
- *
137
- * Measured 2026-08-12 (`probe-param-intersect.ps1`, verdicts re-joined against the CURRENT
138
- * declarations 2026-08-12 — the join is what keeps the rows honest when a declaration changes
139
- * shape). Every marked function has at least one single-value slot the declaration rule would
140
- * insert into, and Excel inserts into none of them: `=EDATE(D1:D5,1)` stays plain and answers
141
- * `#VALUE!`, so inserting would turn Excel's error into a date — over-insertion is corruption,
142
- * not cosmetics.
143
- *
144
- * ABSENT: the declaration decides slot by slot (with {@link slotNever}/{@link slotAlways}
145
- * overrides).
146
- */
147
16
  intersect?: 'never';
148
17
  /**
149
18
  * Per-SLOT suppressions — the function intersects normally at other slots and never at these
@@ -163,132 +32,10 @@ export interface ExcelFunctionFact {
163
32
  * answers `1`. See {@link valueReturn} for the half of that story Excel does not share with us.
164
33
  */
165
34
  slotNever?: readonly number[];
166
- /**
167
- * Per-SLOT forces — range-ACCEPTING slots Excel nonetheless intersects into ("consumed whole"),
168
- * keyed by flattened slot index.
169
- *
170
- * `TRANSPOSE.array` is the one permanent member: a site the body consumes entire
171
- * (`=SUM(TRANSPOSE(A1:A5))` stores as `=SUM(TRANSPOSE(@A1:A5))`, battery A109/A103), and it can
172
- * never lift — the place `site` and `lift` provably come apart. The other members are item 45's
173
- * residue — see the section prose at their rows.
174
- *
175
- * The `*IFS` criteria entries are GONE (2026-08-13), which is the "data, not API" lifecycle
176
- * completing: those five slots now declare `AcceptError<Scalar>` and the ENGINE lifts them, so
177
- * the plain declaration rule answers "site" on its own and the overrides became deletions. The
178
- * retype was not cosmetic — the hand-rolled broadcast in `aggregateIFS` CLAMPED a short criteria
179
- * vector where Excel pads `#N/A`, so `=SUMIFS(D1:D5,D1:D5,H1:H3,D1:D5,I1:I2)` answered
180
- * `140|50|50` against Excel's `140|50|0` (`probe-ifs-broadcast{,2}.ps1`).
181
- */
182
35
  slotAlways?: readonly number[];
183
- /**
184
- * Excel treats the return as ARRAY where the declaration honestly says otherwise — audit 1's
185
- * residue (`probe-return-arrayness{,2}.ps1`).
186
- *
187
- * The selectors are the finding: `IFS`/`SWITCH`/`REDUCE` forward a branch and are marked while
188
- * `IF`/`CHOOSE`/`LET` forward a branch identically and stay plain — so "polymorphic returns are
189
- * arrays" is FALSE; it is a per-function fact in Excel's own signature table, and a table is the
190
- * only honest place for it.
191
- */
192
36
  arrayReturn?: true;
193
- /**
194
- * PROMISES a single value and can hand back a range anyway — rule 3's inner half
195
- * (`probe-call-wrap.ps1` F-block). The declared scalar return must not be believed by
196
- * `_isRangeValued`; the arguments decide instead.
197
- *
198
- * A call is wrapped only when it promises one value and its arguments break the promise. With
199
- * one consumer (`SUM`) and eight inner calls, exactly two wrap:
200
- *
201
- * ```text
202
- * wrapped IFERROR, IFNA declared return: a VALUE, forwarded fallback
203
- * not wrapped IF, CHOOSE, SWITCH, IFS `any` -> not a promise, so it passes through
204
- * not wrapped TRANSPOSE, SEQUENCE an ARRAY return
205
- * not wrapped OFFSET a REFERENCE return
206
- * ```
207
- *
208
- * Why a fact and not the declaration: the two error handlers declare `Scalar` (they promise a
209
- * value, and that promise is load-bearing — it is what refuses `=COLUMN(IFERROR(1,2))` at entry
210
- * as Excel does, INFORMATION.json item 39) while their `valueIfError` BRANCH forwards whatever
211
- * it was given. Nothing in a declaration says "promises a value it cannot always deliver", and
212
- * the one place that needs to know is here. Complementary to {@link arrayReturn}, never
213
- * overlapping: that bit says "really an array", this one says "a value on paper only".
214
- */
215
37
  valueReturn?: true;
216
- /**
217
- * Reads a reference PER CELL — the result is ranged exactly when the argument at this slot is,
218
- * even though the declared return is a single value (CALC-ISSUES item 46). The value is the
219
- * slot the result's extent follows.
220
- *
221
- * These never intersect their reference (nothing collapses the argument) and then hand back one
222
- * value per cell of it, so the mark lands at the ROOT and nowhere else — Excel stores
223
- * `=@COLUMN(D1:D5)`, `=@ROW(D1:D5)`, `=@ISFORMULA(D1:D5)`, `=@FORMULATEXT(D1:D5)`. Neither the
224
- * declaration nor the other facts here can reach this: it is a property of the RESULT that only
225
- * the argument decides.
226
- *
227
- * Measured as the four surviving root-bit rows of `probe-param-intersect.ps1` (of its eight, the
228
- * `IFERROR`/`IFNA` pair closed with rule 3 and both `XLOOKUP` rows with its `IReferenceRange`
229
- * declaration). **Membership is not derivable** — that sweep holds 23 reference-typed (`r:"p"`,
230
- * depth 0) slots and Excel marks the root on 10 of them at identical declared shapes: the
231
- * readers here plus `CELL` (already an {@link arrayReturn} row) and the array/reference returns
232
- * `OFFSET`/`DROP`/`GROUPBY`/`PIVOTBY` (already answered by their return type), while the
233
- * aggregators over the very same shape stay plain (`SUBTOTAL`, `SUMIF`/`COUNTIF`/`AVERAGEIF`
234
- * ranges, `AREAS`, `PHONETIC`). Readers mark, aggregators do not, and no declaration says which.
235
- *
236
- * **The rule is the ARGUMENT's rangedness, not the result's realized extent** — measured on both
237
- * sides, not chosen (`probe-item46-readers2.ps1`). `COLUMN` is the case that separates them,
238
- * since `COLUMN(D1:D5)` over one column evaluates to the single number 4:
239
- *
240
- * ```text
241
- * C1 =SUM(COLUMN(D1:D5)) -> =SUM(@COLUMN(D1:D5)) wrapped, though the result is 1x1
242
- * D1 =COLUMN(D1:D5) modern saves as <c cm="1"><f t="array" ref="A10"> marked, though 1x1
243
- * C5 =SUM(ISFORMULA(F1)) -> unchanged a 1x1 ARGUMENT ranges nothing
244
- * ```
245
- *
246
- * So capability, on the read side AND the write side — in-family with `=SEQUENCE(1)`, which
247
- * Excel also marks at 1×1 (battery A32). That keeps the read insertion and the `cm` writer on
248
- * the ONE rule they are meant to share, and makes our marking canonical rather than merely
249
- * value-identical.
250
- *
251
- * A reader also participates in RULE 3: `=SUM(ROW(D1:D5))` stores as `=SUM(@ROW(D1:D5))` even
252
- * though `SUM` accepts ranges — the collector's tolerance for a reference does not extend to a
253
- * computed array. See `_isValueReturnCall`.
254
- *
255
- * SHAPE, separately (`probe-item46-readers.ps1` block A): `ISFORMULA` and `FORMULATEXT` really
256
- * do hand back one value per cell (both spill 5×1 over a 5-row reference), `ROW` follows the row
257
- * axis and `COLUMN` the column axis, and `CELL` — an {@link arrayReturn} row — does NOT lift at
258
- * all. The `@` alone never proved any of that, which is why it was measured separately.
259
- */
260
38
  readsPerCell?: number;
261
- /**
262
- * The ARRAY SCOPE — the one fact here that is not a property of a single node, THREE-VALUED:
263
- *
264
- * - `'opens'` — the function's range-accepting slots array-evaluate their subtree; the scope
265
- * turns ON beneath them.
266
- * - `'consumer'` | `'lazy'` — the function turns an inherited scope OFF, for itself and
267
- * everything below. The two spellings clear identically; they are kept apart because their
268
- * REASONS are unrelated (a reference collector vs a lazy forwarder — see the section prose at
269
- * their rows), and the reason is what makes the rows readable.
270
- * - ABSENT — the function INHERITS the enclosing scope unchanged. The common case and the
271
- * load-bearing one: a nested `ABS` must leave the scope exactly as it found it.
272
- *
273
- * Everything else in this file is a depth-1 fact about one slot. This is a flag pushed DOWN the
274
- * walk: inside an array-evaluated slot Excel inserts no interior `@`, however scalar the slots
275
- * beneath it are. `=SUMPRODUCT(ABS(B2:B22))` is what needs it — Excel array-evaluates that
276
- * argument and answers `945252`, while the depth-1 rules see `ABS`'s scalar `number` slot
277
- * holding a range, call it a site, and produce `=SUMPRODUCT(ABS(@B2:B22))` — one row, `45003`.
278
- * A wrong NUMBER from a formula that reads as if nothing happened to it.
279
- *
280
- * Measured `probe-slot-class-intersect{,2,3}.ps1` (+ `.json`; 165 cases 2026-08-14, 122 more
281
- * 2026-08-15), then the FULL-ROSTER sweep `probe-slot-class-intersect4.ps1` (1,031 cases over
282
- * 509 functions, 2026-08-15 — every built-in probed in BOTH positions, `=F(…)` at the root and
283
- * `=SUMPRODUCT(F(…))` inside a measured opener, which is what separates opens / clears /
284
- * inherits; `gen-scope-audit.node.test.ts` derives the case list from the live registry).
285
- * Method throughout: a type-matched site candidate (`ABS(B2:B22)` / `UPPER(E2:E22)` /
286
- * `NOT(C2:C22)` — each a one-scalar-slot call over a range, which the `bare` control confirms
287
- * by taking an `@`) entered through legacy `.Formula` and read back through `.Formula2`, with a
288
- * root `@` stripped first so only INTERIOR insertion counts. REFUSED at entry (the `D*`
289
- * database family, `RANK`/`*IFS`/`COUNTBLANK` — Excel rejects a computed array there) is a
290
- * third outcome, not a verdict: those functions keep no row and stay on the default.
291
- */
292
39
  arrayScope?: 'opens' | 'consumer' | 'lazy';
293
40
  /**
294
41
  * Per-SLOT subtree clears — the scope survives the function itself but turns OFF inside these
@@ -312,25 +59,6 @@ export interface ExcelFunctionFact {
312
59
  * array slots and clear at these).
313
60
  */
314
61
  scopeClears?: readonly number[];
315
- /**
316
- * On Excel's volatile-function list — the WRITE-side source of `ca="1"`.
317
- *
318
- * Deliberately a COMPAT fact and not an engine property. Excel needs OFFSET/INDIRECT volatile
319
- * because it cannot statically track where they read; our engine registers the actual target as
320
- * a dynamic precedent at evaluation (`FormulaContext.getReference`), so it recalculates exactly
321
- * when the target changes and gains nothing from every-cycle recalc. But the FILE must still say
322
- * what Excel would say — Excel derives `ca` statically from the formula text, so a cell whose
323
- * formula calls any of these carries `ca="1"` however our engine schedules it. Functions that
324
- * really are runtime-volatile for us too (NOW/RAND/CELL/…) also reach `ca` through the live
325
- * volatile set; this fact is what keeps the flag on the ones that are not.
326
- *
327
- * Membership MEASURED over every `FormulaContext.getReference` consumer
328
- * (`probe-volatile-ca.ps1` + json, 2026-08-14). The measured NOs matter as much:
329
- * INDEX (value AND reference form — `=SUM(INDEX(..):B10)` stays plain), LOOKUP, XLOOKUP, and
330
- * the trim-ref OPERATORS `.:.`/`:.` — not volatile even though TRIMRANGE the function is.
331
- * Also measured there: current Excel adds `aca="1"` beside `ca` on volatile `t="array"` cells
332
- * (INDIRECT/CELL/TRIMRANGE/RANDARRAY), though corpus files from older producers omit it.
333
- */
334
62
  volatile?: true;
335
63
  }
336
64
  /**