@sheetxl/io-xlsx 0.7.28-beta.4 → 0.8.0-beta.10

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 (127) hide show
  1. package/browser/esm/{BXCOn1XvLvYSfpzi.mjs → 2EOdn2WRK5y1L58S.mjs} +193 -143
  2. package/browser/esm/{BknJ4AeVeFJploh9.mjs → B-jb5SuiVh5NnBG_.mjs} +28 -13
  3. package/browser/esm/BKT8OBj-bhQwdg49.mjs +67 -0
  4. package/browser/esm/BLXcoiDAaOMjFuhw.mjs +8056 -0
  5. package/browser/esm/BPmehfSqdvgsLBsB.mjs +5153 -0
  6. package/browser/esm/CI_CZI5m5-KkiAK5.mjs +3559 -0
  7. package/browser/esm/{C3sYFBc7Tym8l12A.mjs → DXopGe8PrLWmwGaV.mjs} +1 -1
  8. package/browser/esm/NQIuOQIleHC4NUW6.mjs +2446 -0
  9. package/browser/esm/index.mjs +2 -3
  10. package/browser/esm/{BhohPLTubb_9rfrh.mjs → xc_LzCPgHn-acgFZ.mjs} +2 -2
  11. package/licenses/dependencies.txt +2 -2
  12. package/node/esm/{B6lQXVQjFT_OE3IA.mjs → BmdmvgO5Zdgx-RWo.mjs} +2 -2
  13. package/node/esm/BpxxiZ2oKPkUSfdB.mjs +2486 -0
  14. package/node/esm/{B9CUp-rqol5K1r1c.mjs → CHqRP_NjPpPd7m9L.mjs} +1 -1
  15. package/node/esm/CtAF486aZqYzMeLM.mjs +3651 -0
  16. package/node/esm/{CfIzBnObj09fDuUX.mjs → O5mti2R9drFOlXc7.mjs} +49 -35
  17. package/node/esm/QS_theNoeqNGLStj.mjs +5298 -0
  18. package/node/esm/index.mjs +40 -25
  19. package/node/esm/nNQ7MG89sGKwkjMA.mjs +4649 -0
  20. package/package.json +7 -8
  21. package/types/src/AutoFilterRules.d.ts +86 -10
  22. package/types/src/ConditionalFormatRules.d.ts +5 -5
  23. package/types/src/DataValidationRules.d.ts +18 -2
  24. package/types/src/ExcelCalcStamp.d.ts +39 -0
  25. package/types/src/ExcelCompat.d.ts +197 -42
  26. package/types/src/ExcelReservedNames.d.ts +3 -4
  27. package/types/src/LegacyFormula.d.ts +28 -7
  28. package/types/src/OOXMLExtensions.d.ts +14 -2
  29. package/types/src/Plugin.d.ts +16 -5
  30. package/types/src/ProtectionAttributes.d.ts +38 -0
  31. package/types/src/SourcePackage.d.ts +31 -12
  32. package/types/src/Types.d.ts +17 -0
  33. package/types/src/reader/HiddenFormulas.d.ts +16 -0
  34. package/types/src/reader/SlicerJoin.d.ts +24 -0
  35. package/types/src/reader/Warning.d.ts +29 -0
  36. package/types/src/reader/ZipReader.d.ts +1 -1
  37. package/types/src/reader/_SlicerRecord.d.ts +37 -0
  38. package/types/src/reader/dom/CustGeomUtils.d.ts +7 -0
  39. package/types/src/reader/dom/DOMTransformer.d.ts +2 -2
  40. package/types/src/reader/dom/ExecutionContext.d.ts +16 -3
  41. package/types/src/reader/dom/Types.d.ts +19 -3
  42. package/types/src/reader/domVisitors/AutoFilterVisitor.d.ts +13 -0
  43. package/types/src/reader/domVisitors/ColorContainerVisitor.d.ts +15 -2
  44. package/types/src/reader/domVisitors/CommentVisitor.d.ts +24 -2
  45. package/types/src/reader/domVisitors/CommentsVisitor.d.ts +2 -2
  46. package/types/src/reader/domVisitors/DrawingCxnSpVisitor.d.ts +1 -0
  47. package/types/src/reader/domVisitors/DrawingElementVisitor.d.ts +32 -1
  48. package/types/src/reader/domVisitors/DrawingGraphicFrameVisitor.d.ts +9 -0
  49. package/types/src/reader/domVisitors/DrawingGrpSpVisitor.d.ts +14 -2
  50. package/types/src/reader/domVisitors/DrawingPicVisitor.d.ts +13 -0
  51. package/types/src/reader/domVisitors/DrawingSpVisitor.d.ts +20 -1
  52. package/types/src/reader/domVisitors/DrawingVisitor.d.ts +10 -0
  53. package/types/src/reader/domVisitors/ExternalLinkVisitor.d.ts +21 -3
  54. package/types/src/reader/domVisitors/FmtSchemeVisitor.d.ts +4 -4
  55. package/types/src/reader/domVisitors/FormControlPrVisitor.d.ts +9 -0
  56. package/types/src/reader/domVisitors/ShapeTextVisitor.d.ts +44 -0
  57. package/types/src/reader/domVisitors/SheetColorContainerVisitor.d.ts +2 -2
  58. package/types/src/reader/domVisitors/SheetStyleVisitor.d.ts +19 -6
  59. package/types/src/reader/domVisitors/SlicerCacheDefinitionVisitor.d.ts +7 -2
  60. package/types/src/reader/domVisitors/SlicersVisitor.d.ts +7 -3
  61. package/types/src/reader/domVisitors/TextPropertiesVisitor.d.ts +13 -1
  62. package/types/src/reader/domVisitors/ThreadedCommentVisitor.d.ts +18 -1
  63. package/types/src/reader/domVisitors/ThreadedCommentsVisitor.d.ts +2 -2
  64. package/types/src/reader/domVisitors/WorkbookVisitor.d.ts +11 -1
  65. package/types/src/reader/domVisitors/index.d.ts +4 -2
  66. package/types/src/reader/sax/LeanSaxParser.d.ts +58 -0
  67. package/types/src/reader/sax/SaxParser.d.ts +11 -1
  68. package/types/src/reader/sax/SaxVisitor.d.ts +3 -2
  69. package/types/src/reader/saxVisitors/ContentTypesVisitor.d.ts +9 -0
  70. package/types/src/reader/saxVisitors/WorksheetVisitor.d.ts +11 -4
  71. package/types/src/utils/DrawingMLText.d.ts +39 -0
  72. package/types/src/utils/FormControls.d.ts +170 -0
  73. package/types/src/utils/VmlNoteShapes.d.ts +135 -0
  74. package/types/src/vba/VBAProject.d.ts +52 -4
  75. package/types/src/writer/builder/ContentTypes.d.ts +13 -0
  76. package/types/src/writer/builder/Emitter.d.ts +11 -6
  77. package/types/src/writer/builder/EmitterRegistry.d.ts +7 -0
  78. package/types/src/writer/builder/OpcXmlUtils.d.ts +2 -0
  79. package/types/src/writer/builder/PackageBuilder.d.ts +72 -22
  80. package/types/src/writer/builder/PartWriter.d.ts +5 -0
  81. package/types/src/writer/builder/RelationshipSet.d.ts +3 -0
  82. package/types/src/writer/builder/Types.d.ts +117 -38
  83. package/types/src/writer/builder/_Types.d.ts +17 -0
  84. package/types/src/writer/emitters/CommentsEmitter.d.ts +58 -0
  85. package/types/src/writer/emitters/EmbeddedPartEmitter.d.ts +60 -0
  86. package/types/src/writer/emitters/ExternalLinkEmitter.d.ts +19 -0
  87. package/types/src/writer/emitters/LegacyDrawingEmitter.d.ts +18 -0
  88. package/types/src/writer/emitters/PersonsEmitter.d.ts +17 -0
  89. package/types/src/writer/emitters/PivotTableEmitter.d.ts +45 -0
  90. package/types/src/writer/emitters/SlicerEmitter.d.ts +66 -0
  91. package/types/src/writer/emitters/StylesEmitter.d.ts +2 -2
  92. package/types/src/writer/emitters/TableEmitter.d.ts +14 -0
  93. package/types/src/writer/emitters/ThreadedCommentsEmitter.d.ts +27 -0
  94. package/types/src/writer/emitters/WorkbookEmitter.d.ts +16 -3
  95. package/types/src/writer/utils/AutoFilter.d.ts +2 -2
  96. package/types/src/writer/utils/CustGeomUtils.d.ts +5 -0
  97. package/types/src/writer/utils/DrawMLUtils.d.ts +57 -3
  98. package/types/src/writer/utils/DummyFunction.d.ts +0 -2
  99. package/types/src/writer/utils/DxfCollector.d.ts +3 -3
  100. package/types/src/writer/utils/HiddenFormulaXfs.d.ts +28 -0
  101. package/types/src/writer/utils/PrstGeomUtils.d.ts +6 -0
  102. package/types/src/writer/utils/TextUtils.d.ts +21 -2
  103. package/browser/cjs/B6sirGz6w-Bm7Ofo.cjs +0 -1
  104. package/browser/cjs/B7_pDFYCVzt-3hUs.cjs +0 -1
  105. package/browser/cjs/Bhq8KfEhCnRykWeS.cjs +0 -1
  106. package/browser/cjs/BmG0GOcbuYvt3-R2.cjs +0 -1
  107. package/browser/cjs/CIpMN7SDVREKQUQE.cjs +0 -6
  108. package/browser/cjs/D3YH3tTndeltJsh5.cjs +0 -1
  109. package/browser/cjs/D5Y4KQhKdukOkjvA.cjs +0 -2
  110. package/browser/cjs/DK9GutW2zPbyNlfU.cjs +0 -2
  111. package/browser/cjs/DWkuoJSgvcXJTdN1.cjs +0 -1
  112. package/browser/cjs/Dmi-Tsz618B6vKpZ.cjs +0 -5
  113. package/browser/cjs/index.cjs +0 -1
  114. package/browser/cjs/xQ6-wbTw5UzZUM1Y.cjs +0 -1
  115. package/browser/esm/BcnofzmeeuCVzr_M.mjs +0 -52
  116. package/browser/esm/C7R1lFA0iv-1bZ9i.mjs +0 -99
  117. package/browser/esm/CV_L3E5OoPstI9lx.mjs +0 -2211
  118. package/browser/esm/D8qZcXzj_fdusd0Y.mjs +0 -4748
  119. package/browser/esm/DLEtaZiz_1cZH0dA.mjs +0 -2685
  120. package/browser/esm/DlBlJGlFQJrKovwJ.mjs +0 -3651
  121. package/browser/esm/saBnxecsRUpY6fGv.mjs +0 -24
  122. package/node/esm/BSrW-J3BEH4Tza_S.mjs +0 -2486
  123. package/node/esm/BYCpXFieBgL_cwTO.mjs +0 -2255
  124. package/node/esm/Bqi4c7-14v0oNgFN.mjs +0 -108
  125. package/node/esm/D0frS50CfyeuXcuz.mjs +0 -2766
  126. package/node/esm/DsZ19z4oXoL-d0Lk.mjs +0 -3740
  127. package/types/src/reader/domVisitors/HyperlinkVisitor.d.ts +0 -6
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@sheetxl/io-xlsx",
3
3
  "description": "SheetXL - Import/Export from/to Excel",
4
- "version": "0.7.28-beta.4",
4
+ "version": "0.8.0-beta.10",
5
5
  "license": "SEE LICENSE IN <LICENSE>",
6
6
  "type": "module",
7
7
  "exports": {
@@ -9,13 +9,12 @@
9
9
  "types": "./types/index.d.ts",
10
10
  "browser": "./browser/esm/index.mjs",
11
11
  "node": "./node/esm/index.mjs",
12
- "import": "./browser/esm/index.mjs",
13
- "require": "./browser/cjs/index.cjs"
12
+ "default": "./browser/esm/index.mjs"
14
13
  }
15
14
  },
16
15
  "types": "./types/index.d.ts",
17
16
  "module": "./browser/esm/index.mjs",
18
- "main": "./browser/cjs/index.cjs",
17
+ "main": "./browser/esm/index.mjs",
19
18
  "sideEffects": false,
20
19
  "engines": {
21
20
  "node": ">=22"
@@ -45,10 +44,10 @@
45
44
  "utilities"
46
45
  ],
47
46
  "dependencies": {
48
- "@sheetxl/sdk": "^0.7.28-beta.4",
49
- "@sheetxl/utils": "^0.7.28-beta.4",
50
- "@xmldom/xmldom": "^0.9.10",
51
- "@zip.js/zip.js": "^2.8.34",
47
+ "@sheetxl/sdk": "^0.8.0-beta.10",
48
+ "@sheetxl/utils": "^0.8.0-beta.10",
49
+ "@xmldom/xmldom": "^0.9.12",
50
+ "@zip.js/zip.js": "^2.23.0",
52
51
  "web-streams-polyfill": "^4.3.0",
53
52
  "xml-formatter": "^3.7.0"
54
53
  }
@@ -1,4 +1,15 @@
1
1
  import { ICondition } from '@sheetxl/sdk';
2
+ /**
3
+ * The `dynamicFilter/@type` values that are a period (ST_DynamicFilterType less the two averages
4
+ * and `null`). The SDK's `last7Days` is not among them.
5
+ */
6
+ export declare const DYNAMIC_FILTER_PERIODS: ReadonlySet<string>;
7
+ /**
8
+ * The condition a `dynamicFilter/@type` means: `aboveAverage` / `belowAverage` are the Average
9
+ * operator, everything else a TimePeriod of that name. The element's `val` / `maxVal` are Excel's
10
+ * cache of its last evaluation, never read.
11
+ */
12
+ export declare function dynamicFilterToJSON(type: string | null | undefined): ICondition.JSON;
2
13
  /**
3
14
  * The border between OOXML's `customFilter` and the SDK's condition.
4
15
  *
@@ -13,10 +24,24 @@ import { ICondition } from '@sheetxl/sdk';
13
24
  * are one table, and a mapping whose halves drift apart is the bug the round-trip corpus exists to
14
25
  * catch.
15
26
  *
16
- * Not handled here, deliberately: the wildcards Excel packs into `@val` for its text filters
17
- * (`val="abc*"` under `equal` is "begins with abc"). Those need `*`/`?`/`~` escaping settled in
18
- * both directions before `startsWith`/`contains`/`endsWith` can be inferred, and a half-done
19
- * inference would turn a literal asterisk into a pattern.
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.
20
45
  */
21
46
  /** A `customFilter` in OOXML's own shape. Reader input, writer output — never persisted. */
22
47
  export interface OOXMLCustomFilter {
@@ -33,18 +58,38 @@ export declare const FilterOperator: {
33
58
  readonly LessThanOrEqual: "lessThanOrEqual";
34
59
  };
35
60
  export type FilterOperator = typeof FilterOperator[keyof typeof FilterOperator];
36
- /** Whether a condition operator is one this border can spell as a `customFilter`. */
37
- export declare function isComparison(operator: unknown): boolean;
38
61
  /**
39
- * `@val` ↦ condition param.
62
+ * Whether a condition can be spelled as one `customFilter`: a comparison or a text operator, plain
63
+ * or under `not`, or an OOXML spelling carried from a file.
64
+ */
65
+ export declare function isCustomFilter(condition: ICondition.JSON | undefined | null): boolean;
66
+ /**
67
+ * The one string of an `inSet` that is Excel's `equal` criterion: under Display, one item, no
68
+ * date groups, no blanks entry and no other part to the set. `null` for any other list.
69
+ */
70
+ export declare function displayListItem(condition: ICondition.JSON | undefined | null): string | null;
71
+ /**
72
+ * Text as a pattern that matches only itself: `~` goes before each `*`, `?` and `~`.
73
+ */
74
+ export declare function escapeWildcards(text: string): string;
75
+ /**
76
+ * `@val` ↦ the param of an ordering comparison.
40
77
  *
41
78
  * @remarks
42
79
  * `@val` is an attribute, so it always arrives as text, but a numeric spelling means the number:
43
- * `equalTo` compares text to text and never coerces, so a numeric column filtered on `val="2"`
44
- * would match nothing at all. This is the same reading the `'=2'` comparison shorthand takes.
80
+ * `greaterThan` orders values, and text never orders against a number. `equal` and `notEqual` are
81
+ * not read through here — they are a one-item values list, whose item is text.
45
82
  */
46
83
  export declare function valToParam(val: string | null | undefined): string | number | undefined;
47
- /** The inverse of {@link valToParam}. */
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
+ */
48
93
  export declare function paramToVal(param: unknown): string | undefined;
49
94
  /**
50
95
  * Reads a `customFilter` as a condition.
@@ -52,6 +97,21 @@ export declare function paramToVal(param: unknown): string | undefined;
52
97
  * @returns The condition, or `null` when the element carries nothing to compare against.
53
98
  */
54
99
  export declare function toCondition(filter: OOXMLCustomFilter, warn?: (message: string) => void): ICondition.JSON | null;
100
+ /**
101
+ * The value test Excel can spell: `and(>= x, <= x)` is `EqualTo x`, and `or(< x, > x)` is
102
+ * `not(EqualTo x)`, for one number `x`. Anything else is returned as it came.
103
+ */
104
+ export declare function foldComparisonPair(condition: ICondition.JSON): ICondition.JSON;
105
+ /**
106
+ * The inverse of {@link foldComparisonPair}: a value `EqualTo` on a number as the two
107
+ * `customFilter` elements of its `customFilters`, with the `and` the pair needs.
108
+ *
109
+ * @returns `null` when the condition is not a value equality on a number, plain or negated.
110
+ */
111
+ export declare function toComparisonPair(condition: ICondition.JSON | undefined | null): {
112
+ and: boolean;
113
+ filters: [OOXMLCustomFilter, OOXMLCustomFilter];
114
+ } | null;
55
115
  /**
56
116
  * The inverse of {@link toCondition}.
57
117
  *
@@ -59,4 +119,20 @@ export declare function toCondition(filter: OOXMLCustomFilter, warn?: (message:
59
119
  * skips it rather than writing an element Excel would reject.
60
120
  */
61
121
  export declare function fromCondition(condition: ICondition.JSON | undefined | null, warn?: (message: string) => void): OOXMLCustomFilter | null;
122
+ /**
123
+ * The values-list item a condition is written as, when Excel writes it that way.
124
+ *
125
+ * @remarks
126
+ * Excel keeps `customFilter` for a pattern and for an ordering comparison. A plain "equals" has
127
+ * neither, and its file holds `<filters><filter val="…"/></filters>`: the text itself, with no
128
+ * escapes, since a values-list item is never a pattern.
129
+ *
130
+ * A number is not written this way: a value `EqualTo` on a number is {@link toComparisonPair},
131
+ * since `<filter val>` would compare the text a cell shows.
132
+ *
133
+ * @returns The item's text (`''` for "equals nothing", which is the blanks entry), or `null` when
134
+ * the condition is not a plain `equalTo` over text or a boolean, under no selector or
135
+ * under Display.
136
+ */
137
+ export declare function toFilterItem(condition: ICondition.JSON | undefined | null): string | null;
62
138
  //# sourceMappingURL=AutoFilterRules.d.ts.map
@@ -1,4 +1,4 @@
1
- import { ICondition, IConditionalFormat, IStyle } from '@sheetxl/sdk';
1
+ import { ICondition, IConditionalFormat, ICellStyle } from '@sheetxl/sdk';
2
2
  /**
3
3
  * The border between OOXML's `cfRule` and the SDK's condition-canonical conditional format.
4
4
  *
@@ -29,7 +29,7 @@ export interface OOXMLCfRule {
29
29
  * and blank/error rules.
30
30
  */
31
31
  formulas?: string[];
32
- style?: IStyle.JSON;
32
+ style?: ICellStyle.JSON;
33
33
  scale?: IConditionalFormat.Scale;
34
34
  stopIfTrue?: boolean;
35
35
  pivot?: boolean;
@@ -69,18 +69,18 @@ export type CfType = typeof CfType[keyof typeof CfType];
69
69
  * @returns The condition, or `null` for the three scale rules and for any type this does not know
70
70
  * (the caller keeps the rule regardless — see design §2.1).
71
71
  */
72
- export declare function toCondition(rule: OOXMLCfRule, warn?: (message: string) => void): ICondition.JSON | null;
72
+ export declare function toCondition(rule: OOXMLCfRule, warn?: (message: string, onceKey?: string) => void): ICondition.JSON | null;
73
73
  /**
74
74
  * The inverse of {@link toCondition}: a condition as OOXML's flat attributes plus the `<formula>`
75
75
  * children Excel expects.
76
76
  *
77
- * @param origin The top-left cell of the rule's FIRST range, in A1 form. Relative references in a
77
+ * @param origin The top-left cell of the bounding box of the rule's ranges, in A1 form. Relative references in a
78
78
  * generated formula are anchored to it (design §2.6).
79
79
  *
80
80
  * @returns `null` when the condition cannot be spelled in OOXML's CF schema; the caller warns and
81
81
  * skips the rule.
82
82
  */
83
- export declare function fromCondition(condition: ICondition.JSON | undefined, origin: string, warn?: (message: string) => void): OOXMLCfRule | null;
83
+ export declare function fromCondition(condition: ICondition.JSON | undefined, origin: string, warn?: (message: string, onceKey?: string) => void): OOXMLCfRule | null;
84
84
  /** The `cfRule/@type` a scale carries. */
85
85
  export declare function scaleToType(scale: IConditionalFormat.Scale): string;
86
86
  //# sourceMappingURL=ConditionalFormatRules.d.ts.map
@@ -43,17 +43,33 @@ 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
+ export declare const MAX_MESSAGE_LENGTH = 255;
52
+ /**
53
+ * `text` cut to {@link MAX_MESSAGE_LENGTH}, never splitting a surrogate pair; `warn` names the
54
+ * attribute when anything is cut.
55
+ */
56
+ export declare function clampMessage(text: string | undefined, attribute: string, warn?: (message: string, onceKey?: string) => void): string | undefined;
57
+ /**
58
+ * Whether formula `text` is a union reference (`($A$1,$A$8)`, `A1,A8`): a comma outside every
59
+ * function call, string, quoted sheet name and array constant.
60
+ */
61
+ export declare function isUnionFormula(text: string): boolean;
46
62
  /**
47
63
  * Reads a `dataValidation`'s type/operator/formulas as a condition.
48
64
  *
49
65
  * @returns The condition, or `null` for a prompt-only validation (no `type`, Excel's "Any value").
50
66
  */
51
- export declare function toCondition(rule: OOXMLDataValidation, warn?: (message: string) => void): ICondition.JSON | null;
67
+ export declare function toCondition(rule: OOXMLDataValidation, warn?: (message: string, onceKey?: string) => void): ICondition.JSON | null;
52
68
  /**
53
69
  * The inverse of {@link toCondition}.
54
70
  *
55
71
  * @returns `null` when the condition cannot be spelled in OOXML; the caller warns and writes the
56
72
  * validation as prompt-only rather than dropping it.
57
73
  */
58
- export declare function fromCondition(condition: ICondition.JSON | undefined, warn?: (message: string) => void): OOXMLDataValidation | null;
74
+ export declare function fromCondition(condition: ICondition.JSON | undefined, warn?: (message: string, onceKey?: string) => void): OOXMLDataValidation | null;
59
75
  //# sourceMappingURL=DataValidationRules.d.ts.map
@@ -0,0 +1,39 @@
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
+ 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
+ export declare const EXCEL_CALC_FEATURES_VERIFIED: string;
39
+ //# sourceMappingURL=ExcelCalcStamp.d.ts.map
@@ -1,4 +1,4 @@
1
- import { IFunction, ICalculation } from '@sheetxl/sdk';
1
+ import { IFunction, IRange, INamed, ISheet, ICalculation } from '@sheetxl/sdk';
2
2
  /**
3
3
  * The implicit-intersection translation between the modern (dynamic) formula model and what a
4
4
  * legacy xlsx `<f>` means — item 47's `ExcelCompat.ts`, born in io-xlsx
@@ -9,12 +9,29 @@ import { IFunction, ICalculation } from '@sheetxl/sdk';
9
9
  *
10
10
  * - READ (rules 1/2): a plain `<f>` — no `t="array"`, no `cm` — has legacy semantics whatever its
11
11
  * age, and loading it means putting the `@` back where Excel would
12
- * (`=ABS(A1:A5)` → `=ABS(@A1:A5)`). The reader wraps exactly those formulas in the
13
- * {@link INTERSECT_MARKER} pseudo-function, which is how the per-CELL decision reaches a
14
- * per-FORMULA transform; {@link createCompatReadTransform} strips the marker at the root and
15
- * injects.
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`).
16
17
  * - WRITE: the `cm="1"` + `t="array"` marker goes on every formula legacy intersection would
17
- * change — {@link hasIntersectionSite}, consumed by `WorksheetEmitter`.
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).
18
35
  *
19
36
  * ### Two kinds of arrayness, and only one of them is a site
20
37
  *
@@ -42,48 +59,40 @@ import { IFunction, ICalculation } from '@sheetxl/sdk';
42
59
  * predicate"). Re-run the probes when adding a function — no test can detect a new function Excel
43
60
  * happens to disagree with.
44
61
  */
45
- /**
46
- * The reader's per-cell legacy marker — a pseudo-function the reader wraps around every formula
47
- * persisted WITHOUT array semantics, so the (single, per-formula) parse transform can see the
48
- * per-cell dialect bit in the tree itself.
49
- *
50
- * @remarks
51
- * The same idiom as `__xludf.DUMMYFUNCTION`: formula text only this package writes and only this
52
- * package strips, alive purely between the reader's JSON assembly and the parse-time transform.
53
- * If the transform is ever missing the marker surfaces as a loud `#NAME?`, never as a silently
54
- * wrong value.
55
- */
56
- export declare const INTERSECT_MARKER = "__sxl.INTERSECT";
57
62
  /** Does any call in this tree name a function on Excel's volatile list
58
63
  * (`ExcelFunctionFact.volatile`)? (Defined-name bodies are not chased: Excel's `ca` reflects the
59
64
  * CELL's own formula text.) */
60
65
  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
+ export declare const hasUnknownCall: (root: ICalculation.FormulaNode | undefined, ctx: CompatContext) => boolean;
73
+ /** What the walks read of a function: its declared slots and return, and whether it is a built-in. */
74
+ export interface CompatFunction {
75
+ getDeclaration(): IFunction.IDeclaration;
76
+ isBuiltIn(): boolean;
77
+ }
61
78
  /**
62
79
  * The resolution context the walks need — everything else is the formula's own tree.
63
80
  */
64
81
  export interface CompatContext {
65
- /** Resolves a canonical function name against the live registry, or `null` when unknown. */
66
- getFunction(name: string): IFunction | null;
82
+ /** Resolves a canonical function name to its declaration, or `null` when unknown. */
83
+ getFunction(name: string): CompatFunction | null;
84
+ /**
85
+ * Is there a registry to ask at all? Separates "this name is not a function" from "nothing can
86
+ * be resolved yet" — the two read identically through {@link getFunction}, and only the first
87
+ * is evidence of an unknown function.
88
+ */
89
+ hasFunctions(): boolean;
67
90
  /**
68
91
  * The lite root of a defined name's body, or `null` when the name is unresolvable — an
69
92
  * unresolved name evaluates to `#NAME?`, which is never a range.
70
93
  */
71
94
  getNamedRoot(name: string, scope?: string | null): ICalculation.FormulaNode | null;
72
95
  }
73
- /**
74
- * Builds a {@link CompatContext} over a (lazily supplied) calculation.
75
- *
76
- * @param calculation Deferred on purpose: at READ time the transform is constructed before the
77
- * `Workbook` it serves — formulas compile in queued load drains after the constructor returns, so
78
- * the reference is live by the first call. Defined names hydrate ahead of cell formulas (the
79
- * calculation's priority drain), which is what makes a name's body answerable mid-load.
80
- *
81
- * @remarks
82
- * The name-body lookup reads the LIVE item through the public
83
- * `getExpression({ formulaTransform })` collector — the same live-model pattern the emitter uses — and
84
- * memoizes per name for the context's (load- or save-long) lifetime.
85
- */
86
- export declare function createCompatContext(calculation: () => ICalculation | null | undefined): CompatContext;
87
96
  /**
88
97
  * Rules 1/2 — rewrites a LEGACY formula into its modern equivalent by inserting `@` at every
89
98
  * implicit-intersection site, exactly as Excel does when it opens a pre-dynamic-array cell.
@@ -127,16 +136,162 @@ export declare const insertImplicitIntersection: (root: ICalculation.FormulaNode
127
136
  * open alternative.
128
137
  */
129
138
  export declare const hasIntersectionSite: (root: ICalculation.FormulaNode, ctx: CompatContext) => boolean;
139
+ /** The reader's two READ transforms — see {@link createCompatReadTransforms}. */
140
+ export interface CompatReadTransforms {
141
+ /**
142
+ * The legacy SPELLING unwrap alone (`createLegacyReadTransform`). What a cell the file marked
143
+ * modern (`cm=`/`t="array"`) takes, and what every defined name takes.
144
+ */
145
+ base: ICalculation.FormulaTransform;
146
+ /** {@link base} plus the rules-1/2 `@` insertion at the root. What a plain `<f>` takes. */
147
+ legacy: ICalculation.FormulaTransform;
148
+ }
149
+ /**
150
+ * The reader's READ transforms, one per dialect: the legacy spelling unwrap on every node, and —
151
+ * for a formula the file stored PLAIN — the rules-1/2 insertion at the root.
152
+ *
153
+ * @remarks
154
+ * Which one a formula takes is a per-CELL question, answered from the same `sheet.formulaArray`
155
+ * the file's `cm=`/`t="array"` attributes were read into: the load asks the dialect's `read`
156
+ * once per formula block and hands it `isArrayAnchor`. Defined names have no cell to have
157
+ * provenance from and take {@link base}.
158
+ *
159
+ * Both are no-op-safe on a partially parsed (errored) tree — the walks skip absent inputs and a
160
+ * tree with no site is returned unchanged.
161
+ */
162
+ export declare function createCompatReadTransforms(ctx: CompatContext): CompatReadTransforms;
163
+ /**
164
+ * What the xlsx dialect says about one formula, for the attributes that sit beside `<f>`. Absent
165
+ * altogether when neither holds.
166
+ */
167
+ export interface XlsxFormulaAnnotation {
168
+ /**
169
+ * The formula has to carry dynamic-array semantics (`cm=`): legacy implicit intersection would
170
+ * change what it means ({@link hasIntersectionSite}).
171
+ */
172
+ cm?: true;
173
+ /**
174
+ * Excel recalculates the cell on every pass (`ca="1"`): it calls a function on Excel's volatile
175
+ * list, or one Excel does not know ({@link hasVolatileCall}, {@link hasUnknownCall}).
176
+ */
177
+ ca?: true;
178
+ }
179
+ /** Where a save's emitters find the workbook's dialect (`EmitContext.getSharedStates`). */
180
+ export declare const SHARED_STATE_XLSX_FORMULA_DIALECT = "xlsxFormulaDialect";
130
181
  /**
131
- * The reader's complete READ transform: the legacy spelling unwrap on every node
132
- * ({@link createLegacyReadTransform}), plus — at the root of a formula the reader wrapped in
133
- * {@link INTERSECT_MARKER} — the marker strip and rules-1/2 insertion.
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
+ export interface XlsxFormulaDialect {
205
+ /**
206
+ * The tree of the model's canonical text written at `anchor`, in the shape the compiled tree
207
+ * has (`FormulaText.ParseOptions.normalize`), or `null` when it does not parse.
208
+ */
209
+ parse(text: string, anchor?: IRange.CellCoords): ICalculation.FormulaNode | null;
210
+ /**
211
+ * Canonical text for a file's cell formula. Text that does not parse comes back as it is.
212
+ * @param isArrayAnchor The cell is the top-left of a `t="array"` extent: no `@` insertion.
213
+ */
214
+ readText(text: string, anchor: IRange.CellCoords, isArrayAnchor: boolean): string;
215
+ /**
216
+ * Canonical text for a file's detached formula — a defined name, a condition operand, a cfvo
217
+ * value: the spelling unwrap alone, at no anchor. Text that does not parse comes back as it is.
218
+ */
219
+ readDetached(text: string): string;
220
+ /** The `cm=` and `ca=` facts about a formula, asked of its canonical tree. */
221
+ annotate(root: ICalculation.FormulaNode): XlsxFormulaAnnotation | undefined;
222
+ /**
223
+ * The tree spelled for the file. The same object when nothing legacy is in it.
224
+ * @param isArrayAnchor The block is an array anchor: its `@`s stay explicit.
225
+ * @param homeTable The table the formula's cell is in, if any. The model images a reference
226
+ * to the formula's own table without the name (`[@Qty]`, as Excel displays it); the file wants
227
+ * it qualified.
228
+ */
229
+ spell(root: ICalculation.FormulaNode, isArrayAnchor: boolean, homeTable?: string | null): ICalculation.FormulaNode;
230
+ /** A defined name's canonical text spelled for the file. */
231
+ writeName(text: string): string;
232
+ }
233
+ /**
234
+ * Builds the dialect for a workbook.
235
+ *
236
+ * @param names The workbook's defined names, as the file or the model has them. A name's body is
237
+ * parsed when a rule first asks whether the name is range-valued; a bare built-in is eta-prefixed
238
+ * on write only while no name claims the spelling.
239
+ * @param tables The workbook's table names. A bare table name (`=Sales`) parses as a name; the
240
+ * file spells it as the table's data body (`Sales[]`), so the writer has to know which names are
241
+ * tables.
242
+ */
243
+ export declare function createXlsxFormulaDialect(names?: readonly INamed.JSON[] | null, tables?: readonly string[] | null): XlsxFormulaDialect;
244
+ /**
245
+ * Rewrites a sheet's formulas, as the reader recorded them, into canonical text in place. Plain
246
+ * versus marked is a per-CELL fact on disk (`cm=` / `t="array"` are cell attributes), answered
247
+ * from the `formulaArray` extents the reader recorded.
248
+ */
249
+ export declare function readSheetFormulas(sheet: ISheet.JSON, dialect: XlsxFormulaDialect): void;
250
+ /**
251
+ * The `@` nodes of a modern tree that the legacy read would put back on its own — the ones a
252
+ * PLAIN `<f>` does not need to spell.
253
+ *
254
+ * @remarks
255
+ * The exact inverse of {@link insertImplicitIntersection}, asked per `@`: with the operator
256
+ * stripped, is its operand at a site of the enclosing node (rules 2/3, in the scope and demand
257
+ * the enclosing position pushes down) — or, at the root, range-valued (rule 1)? Every other `@`
258
+ * in the tree stays where it is while one is asked about, which is what the insertion's
259
+ * post-order sees too: by the time it examines a node its children already carry their `@`s.
260
+ * The per-slot rules read one slot at a time, so stripping every candidate of a node at once is
261
+ * the same question as stripping each alone.
262
+ *
263
+ * An `@` directly over a PAREN is never implied: the read inserts INSIDE parens
264
+ * ({@link _at}), so `@(A1:A5)` is not a spelling it produces — measured `_xlfn.SINGLE((A1:A5))`.
265
+ *
266
+ * Only meaningful on a tree WITHOUT sites ({@link hasIntersectionSite} false): a marked cell
267
+ * takes no insertion on read, so every `@` on it has to be explicit.
268
+ */
269
+ export declare const impliedIntersections: (root: ICalculation.FormulaNode, ctx: CompatContext) => Set<ICalculation.FormulaNode>;
270
+ /**
271
+ * The writer's complete WRITE transform for a CELL formula: the legacy spelling on every node
272
+ * (`createLegacyWriteTransform`), plus — at the root of a formula that will be written plain —
273
+ * the elision of every `@` the legacy read would put back.
134
274
  *
135
275
  * @remarks
136
- * Defined names and array-anchored cells arrive UNWRAPPED, so they take the spelling pass only —
137
- * no marker, no insertion; the per-cell dialect decision was the reader's and rode in on the
138
- * marker. No-op-safe on an errored tree: a root that is not the marker (the parse broke before
139
- * the wrapper closed) is left alone.
276
+ * Excel's own spelling of a modern `@`, measured `probe-at-elision.ps1` (2026-09-03): `=@A1:A5`
277
+ * saves as `A1:A5`, `=ABS(@A1:A5)` as `ABS(A1:A5)`, `=@FOO(1)` as `FOO(1)`, `=@SEQUENCE(5)` as
278
+ * `_xlfn.SEQUENCE(5)`; `_xlfn.SINGLE` appears only where the read would NOT re-insert —
279
+ * `SUM(_xlfn.SINGLE(A1:A5))`, `SUMPRODUCT(ABS(_xlfn.SINGLE(A1:A5)))`, `_xlfn.SINGLE(SUM(1))`,
280
+ * `_xlfn.SINGLE((A1:A5))`. A formula that still has a site after its `@`s are honored is a
281
+ * MARKED cell (`cm="1"`) and keeps every `@` explicit (`=@ABS(A1:A5)` →
282
+ * `_xlfn.SINGLE(ABS(A1:A5))` under `cm="1"`), because no insertion runs on it. The text is
283
+ * therefore self-consistent in both readers: what comes back is the tree that went out.
284
+ *
285
+ * This is why the SpreadJS/add-in round trip closes: `=@CASCADESPARKLINE(...)` — the modern
286
+ * form of the plain `<f>` the authoring application wrote — goes back out as that same plain
287
+ * `<f>`, which is the only spelling the authoring application knows.
288
+ *
289
+ * Mechanics: the spelling runs in the SDK's own post-order walk (fresh nodes keep their trivia
290
+ * that way), so by the root every `@` is already a `SINGLE` call. The root pass unwraps a VIEW of
291
+ * the spelled tree to ask the modern-tree questions, maps each implied `@` of the view back to
292
+ * the `SINGLE` node it came from, and drops those nodes copy-on-write — every untouched node
293
+ * keeps its identity, and its whitespace. Defined names and array-anchored cells take the
294
+ * spelling pass only (`WorkbookEmitter`'s write provider decides per block; names never run this).
140
295
  */
141
- export declare function createCompatReadTransform(calculation: () => ICalculation | null | undefined): ICalculation.FormulaTransform;
296
+ export declare function createCompatWriteTransform(legacy: ICalculation.FormulaTransform, ctx: CompatContext): ICalculation.FormulaTransform;
142
297
  //# sourceMappingURL=ExcelCompat.d.ts.map
@@ -21,10 +21,9 @@
21
21
  * ### Provenance
22
22
  *
23
23
  * Candidates come from two sources: MS-XLSX §2.2.2 `command-list` + `ref-macro-function-call` +
24
- * `macro-function-call` (505 names), and Excel Online's own function-id enum
25
- * (`excel-online-ftab.txt`, 708 entries), which is the better authority — it is what Excel
26
- * RECOGNIZES rather than what Microsoft documented, and it carries names the productions never
27
- * list. `SERIES` is the one that matters here: the chart-series function, absent from every
24
+ * `macro-function-call` (505 names), and the function names Excel itself recognizes (708
25
+ * entries), which is the better authority — it is what Excel RECOGNIZES rather than what
26
+ * Microsoft documented, and it carries names the productions never list. `SERIES` is the one that matters here: the chart-series function, absent from every
28
27
  * MS-XLSX production and fatal in a worksheet cell.
29
28
  *
30
29
  * Membership in either source is NOT the verdict — `FILTER`, `IF` and `SORT` appear in them and