@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.
- package/browser/esm/{9dwUocbOsJuAcmKn.mjs → BjkdoGjLpkKUlK5q.mjs} +2234 -2250
- package/browser/esm/{DeMZN_qj__PKo4Wh.mjs → Bomb4K5f16UyiyED.mjs} +1 -1
- package/browser/esm/{D8k22TSWPd_RHEpj.mjs → Bs0IJqyry5ZycCBU.mjs} +988 -1008
- package/browser/esm/CIRY1QIACITHu_lA.mjs +24 -0
- package/browser/esm/{DVLJTjJCGqrJUa8c.mjs → Cs4lg7bxClbTkldF.mjs} +61 -61
- package/browser/esm/{aUBXbTh2r0u3x4Xo.mjs → DAYdoS9sLmYf8kzD.mjs} +2 -2
- package/browser/esm/{BIvDjK4Zl8bWRgl8.mjs → DKWU_JYjVmtOzTGr.mjs} +2 -2
- package/browser/esm/{DsppUz-14Z7ti9i3.mjs → DN7ig6HovGU5gMbr.mjs} +1 -1
- package/browser/esm/{CcH5ITJFTMVWUJO9.mjs → DbygDdjktfjoU4DI.mjs} +1041 -1041
- package/browser/esm/{DO75RoAQTgMuVzXv.mjs → DiNNY0EgHikWbrDz.mjs} +2 -2
- package/browser/esm/{DKnOwucZq4z9_-r-.mjs → QuYxg3ec6kN-djPF.mjs} +4 -4
- package/browser/esm/index.mjs +2 -2
- package/node/esm/{C78E45n6j2E8rruH.mjs → BCSJ_kqVLXkZlYh3.mjs} +818 -819
- package/node/esm/{DXusvwW73FUDSyvD.mjs → BCXSNXHvNQ9JQMLE.mjs} +1129 -1129
- package/node/esm/{DsyuWxk3bdGhJUQN.mjs → BycDf9HTtfpzL-zt.mjs} +1 -1
- package/node/esm/{BmIIQODk4dBVIXA4.mjs → CTdvEKRTM-W1L1KU.mjs} +976 -994
- package/node/esm/{DCaAOfuW-w_dx_qd.mjs → CkenuXqno-ffP331.mjs} +2 -2
- package/node/esm/{CDKm5s3JE_d99TJw.mjs → CvcAx132Yp5uUDUB.mjs} +81 -81
- package/node/esm/{C-e5AO_4TnGywT-m.mjs → H9egT6kWCw8RAf76.mjs} +1 -1
- package/node/esm/{DSgxL0sBZtWMydVl.mjs → TPq4Re0SQgONsX_u.mjs} +2 -2
- package/node/esm/index.mjs +4 -4
- package/package.json +3 -3
- package/types/src/AutoFilterRules.d.ts +0 -42
- package/types/src/DataTableFormula.d.ts +0 -10
- package/types/src/DataValidationRules.d.ts +0 -5
- package/types/src/ExcelCalcStamp.d.ts +0 -36
- package/types/src/ExcelCompat.d.ts +0 -140
- package/types/src/ExcelFunctionFacts.d.ts +0 -272
- package/types/src/ExcelReservedNames.d.ts +0 -64
- package/types/src/KnownFonts.d.ts +0 -13
- package/types/src/LegacyFormula.d.ts +0 -58
- package/types/src/Plugin.d.ts +3 -3
- package/types/src/SheetKinds.d.ts +0 -15
- package/types/src/SourcePackage.d.ts +0 -44
- package/types/src/Types.d.ts +2 -3
- package/types/src/chart/_chartExStyle.d.ts +0 -9
- package/types/src/reader/DummyFunctionUnwrap.d.ts +43 -23
- package/types/src/reader/domVisitors/AutoFilterVisitor.d.ts +0 -8
- package/types/src/reader/domVisitors/ExternalLinkVisitor.d.ts +0 -10
- package/types/src/reader/domVisitors/FeaturePropertyBagVisitor.d.ts +0 -9
- package/types/src/reader/domVisitors/FmtSchemeVisitor.d.ts +0 -11
- package/types/src/reader/domVisitors/WorkbookVisitor.d.ts +0 -9
- package/types/src/reader/saxVisitors/SharedStringsVisitor.d.ts +0 -15
- package/types/src/reader/saxVisitors/WorksheetVisitor.d.ts +3 -1
- package/types/src/richValue/WebImageRichValueHandler.d.ts +0 -5
- package/types/src/utils/VmlNoteStyle.d.ts +0 -19
- package/types/src/vba/VBAProject.d.ts +0 -19
- package/types/src/writer/builder/OpcXmlUtils.d.ts +0 -8
- package/types/src/writer/builder/PackageBuilder.d.ts +0 -41
- package/types/src/writer/builder/Types.d.ts +0 -30
- package/types/src/writer/emitters/ExternalLinkEmitter.d.ts +0 -11
- package/types/src/writer/emitters/FeaturePropertyBagEmitter.d.ts +0 -10
- package/types/src/writer/utils/DefaultRows.d.ts +0 -16
- 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
|
/**
|