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

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 (89) hide show
  1. package/browser/cjs/BzOEBR0jaxXg9wvt.cjs +5 -0
  2. package/browser/cjs/C8oC1tPbhgR0Dqtx.cjs +2 -0
  3. package/browser/cjs/Ca-xJDjg5bOpUPXX.cjs +1 -0
  4. package/browser/cjs/{D5Y4KQhKdukOkjvA.cjs → D3EWCPfCu-qMOIGd.cjs} +1 -2
  5. package/browser/cjs/{DK9GutW2zPbyNlfU.cjs → DULsYP_GcPGLVYSE.cjs} +10 -1
  6. package/browser/cjs/DtBN3UOzNJjYBwJ6.cjs +1 -0
  7. package/browser/cjs/index.cjs +1 -1
  8. package/browser/cjs/sNZR19Wk-XQ2xZ9E.cjs +1 -0
  9. package/browser/esm/B9q618XELV7uWJsA.mjs +67 -0
  10. package/browser/esm/{D8qZcXzj_fdusd0Y.mjs → BwbMurFOptAFs7gC.mjs} +1596 -1130
  11. package/browser/esm/{BhohPLTubb_9rfrh.mjs → CMHb6pUUmsCP9r_9.mjs} +2 -2
  12. package/browser/esm/{saBnxecsRUpY6fGv.mjs → CMzkLUwbgA73RvCb.mjs} +1 -1
  13. package/browser/esm/D75_rfogFUfXADKc.mjs +3324 -0
  14. package/browser/esm/{DlBlJGlFQJrKovwJ.mjs → DfuBawaydlvgZMR-.mjs} +1827 -1050
  15. package/browser/esm/{BknJ4AeVeFJploh9.mjs → DhqYgh9G2vLn7mIE.mjs} +28 -13
  16. package/browser/esm/DoMlKUCnMSlR2qX5.mjs +159 -0
  17. package/browser/esm/{CV_L3E5OoPstI9lx.mjs → DtpWa7tZahylJ3HS.mjs} +446 -347
  18. package/browser/esm/{BXCOn1XvLvYSfpzi.mjs → IZf0hIeLYj3T0Xvu.mjs} +2 -2
  19. package/browser/esm/{C3sYFBc7Tym8l12A.mjs → _UDbQq5-pHbU1f82.mjs} +1 -1
  20. package/browser/esm/index.mjs +3 -3
  21. package/node/esm/{DsZ19z4oXoL-d0Lk.mjs → BD03jrMQ_UKA196-.mjs} +1937 -1142
  22. package/node/esm/{B6lQXVQjFT_OE3IA.mjs → Bi_kZVtZams7taqa.mjs} +2 -2
  23. package/node/esm/{BYCpXFieBgL_cwTO.mjs → BxHvzSROx_N_7nJH.mjs} +607 -506
  24. package/node/esm/{CfIzBnObj09fDuUX.mjs → CB1ijGbhl-e2l6Mm.mjs} +49 -35
  25. package/node/esm/CO1M1H1N6fB422K-.mjs +2959 -0
  26. package/node/esm/CWpezSa6TERGEv-B.mjs +3410 -0
  27. package/node/esm/{B9CUp-rqol5K1r1c.mjs → CY-pSutJLHskZfXZ.mjs} +1 -1
  28. package/node/esm/Dezt2uIDqlxjiuk5.mjs +170 -0
  29. package/node/esm/index.mjs +40 -25
  30. package/package.json +3 -3
  31. package/types/src/ConditionalFormatRules.d.ts +3 -3
  32. package/types/src/DataValidationRules.d.ts +18 -2
  33. package/types/src/ExcelCalcStamp.d.ts +39 -0
  34. package/types/src/ExcelCompat.d.ts +197 -42
  35. package/types/src/LegacyFormula.d.ts +28 -7
  36. package/types/src/Plugin.d.ts +16 -5
  37. package/types/src/ProtectionAttributes.d.ts +38 -0
  38. package/types/src/SourcePackage.d.ts +31 -12
  39. package/types/src/Types.d.ts +17 -0
  40. package/types/src/reader/HiddenFormulas.d.ts +16 -0
  41. package/types/src/reader/Warning.d.ts +29 -0
  42. package/types/src/reader/dom/DOMTransformer.d.ts +1 -1
  43. package/types/src/reader/dom/ExecutionContext.d.ts +16 -3
  44. package/types/src/reader/dom/Types.d.ts +19 -3
  45. package/types/src/reader/domVisitors/CommentVisitor.d.ts +18 -1
  46. package/types/src/reader/domVisitors/CommentsVisitor.d.ts +2 -2
  47. package/types/src/reader/domVisitors/ExternalLinkVisitor.d.ts +21 -3
  48. package/types/src/reader/domVisitors/SheetColorContainerVisitor.d.ts +2 -2
  49. package/types/src/reader/domVisitors/SheetStyleVisitor.d.ts +6 -1
  50. package/types/src/reader/domVisitors/ThreadedCommentVisitor.d.ts +9 -1
  51. package/types/src/reader/domVisitors/ThreadedCommentsVisitor.d.ts +2 -2
  52. package/types/src/reader/domVisitors/WorkbookVisitor.d.ts +11 -1
  53. package/types/src/reader/sax/LeanSaxParser.d.ts +58 -0
  54. package/types/src/reader/sax/SaxParser.d.ts +11 -1
  55. package/types/src/reader/sax/SaxVisitor.d.ts +3 -2
  56. package/types/src/reader/saxVisitors/ContentTypesVisitor.d.ts +9 -0
  57. package/types/src/reader/saxVisitors/WorksheetVisitor.d.ts +11 -4
  58. package/types/src/utils/VmlNoteShapes.d.ts +75 -0
  59. package/types/src/vba/VBAProject.d.ts +52 -4
  60. package/types/src/writer/builder/ContentTypes.d.ts +13 -0
  61. package/types/src/writer/builder/Emitter.d.ts +6 -6
  62. package/types/src/writer/builder/EmitterRegistry.d.ts +7 -0
  63. package/types/src/writer/builder/OpcXmlUtils.d.ts +2 -0
  64. package/types/src/writer/builder/PackageBuilder.d.ts +70 -22
  65. package/types/src/writer/builder/PartWriter.d.ts +5 -0
  66. package/types/src/writer/builder/RelationshipSet.d.ts +3 -0
  67. package/types/src/writer/builder/Types.d.ts +107 -38
  68. package/types/src/writer/builder/_Types.d.ts +17 -0
  69. package/types/src/writer/emitters/CommentsEmitter.d.ts +52 -0
  70. package/types/src/writer/emitters/EmbeddedPartEmitter.d.ts +60 -0
  71. package/types/src/writer/emitters/ExternalLinkEmitter.d.ts +19 -0
  72. package/types/src/writer/emitters/LegacyDrawingEmitter.d.ts +18 -0
  73. package/types/src/writer/emitters/PersonsEmitter.d.ts +17 -0
  74. package/types/src/writer/emitters/PivotTableEmitter.d.ts +45 -0
  75. package/types/src/writer/emitters/ThreadedCommentsEmitter.d.ts +21 -0
  76. package/types/src/writer/emitters/WorkbookEmitter.d.ts +16 -3
  77. package/types/src/writer/utils/DrawMLUtils.d.ts +16 -1
  78. package/types/src/writer/utils/HiddenFormulaXfs.d.ts +28 -0
  79. package/browser/cjs/Bhq8KfEhCnRykWeS.cjs +0 -1
  80. package/browser/cjs/BmG0GOcbuYvt3-R2.cjs +0 -1
  81. package/browser/cjs/D3YH3tTndeltJsh5.cjs +0 -1
  82. package/browser/cjs/DWkuoJSgvcXJTdN1.cjs +0 -1
  83. package/browser/cjs/Dmi-Tsz618B6vKpZ.cjs +0 -5
  84. package/browser/esm/BcnofzmeeuCVzr_M.mjs +0 -52
  85. package/browser/esm/C7R1lFA0iv-1bZ9i.mjs +0 -99
  86. package/browser/esm/DLEtaZiz_1cZH0dA.mjs +0 -2685
  87. package/node/esm/BSrW-J3BEH4Tza_S.mjs +0 -2486
  88. package/node/esm/Bqi4c7-14v0oNgFN.mjs +0 -108
  89. package/node/esm/D0frS50CfyeuXcuz.mjs +0 -2766
@@ -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
@@ -17,10 +17,27 @@ export { XLFN, XLWS } from './ExcelFunctionFacts';
17
17
  * | trim-range | infix `.:.` / `.:` / `:.` | `_xlfn._TRO_ALL/_TRO_LEADING/_TRO_TRAILING(a:b)` |
18
18
  * | bare built-in | named `SUM` (unresolved) | `_xleta.SUM` — from the MEASURED `ExcelFunctionFacts` map |
19
19
  * | LET/LAMBDA parameter | named `x` | `_xlpm.x` — at the declaration AND at every use |
20
+ * | long string literal | `"…"` over 255 characters | `_xlfn._LONGTEXT("…255…","…255…",…)` |
20
21
  *
21
22
  * MS-XLSX Extensions to Office Open XML section 2.2.2 Formula:
22
23
  * https://learn.microsoft.com/en-us/openspecs/office_standards/ms-xlsx/3d025add-118d-4413-9856-ab65712ec1b0
23
24
  */
25
+ /**
26
+ * The wrapper Excel spells a string literal longer than {@link LONGTEXT_CHUNK} characters with:
27
+ * the literal cut into chunks of at most that many characters, each a string argument, in order.
28
+ * Excel's formula grammar caps a literal at 255 characters; the model has no such cap and holds
29
+ * the literal whole, so the wrapper exists only on disk.
30
+ *
31
+ * Measured (Excel 16.0, 2026-09-23, `probe-dv-launder.ps1`): a 996-character data-validation list
32
+ * literal saved as `_xlfn._LONGTEXT("…","…","…","…")` with chunks of 255, 255, 255 and 231
33
+ * characters (`__tests__/data/conditions/dv-limits.xlsx`). The chunk is counted on the literal's
34
+ * characters, not its imaged form — how a doubled quote (`""`) counts toward the 255 is not yet
35
+ * measured. Excel opens a bare over-long literal in a DV formula (same probe); whether it opens
36
+ * one in a cell `<f>` is unmeasured, so the wrapper is written wherever Excel would write it.
37
+ */
38
+ export declare const LONGTEXT = "_LONGTEXT";
39
+ /** The longest string literal Excel spells bare — see {@link LONGTEXT}. */
40
+ export declare const LONGTEXT_CHUNK = 255;
24
41
  /**
25
42
  * Eta-reduced-lambda prefix — a BUILT-IN function referenced WITHOUT parentheses
26
43
  * (`=BYROW(A1:B3,SUM)`, and equally `=SUM(ABS)` or `=1+ABS`: Excel prefixes it wherever it
@@ -44,10 +61,12 @@ export declare const XLPM = "_xlpm.";
44
61
  export declare const XLOP = "_xlop.";
45
62
  /**
46
63
  * The write direction: modern (dynamic) tree → on-disk xlsx spellings, as an
47
- * {@link ICalculation.FormulaTransform} handed to `toJSON({ formulaTransform })`.
64
+ * {@link ICalculation.FormulaTransform} — the `write` half of the xlsx dialect (`ExcelCompat`).
48
65
  *
49
- * @param definedNames Upper-cased spellings of the workbook's defined names. A bare name that
50
- * resolves to a REAL defined name is a name, not an eta-reduced built-in, and stays bare.
66
+ * @param definedNames Answers whether an upper-cased spelling is one of the workbook's defined
67
+ * names. A bare name that resolves to a REAL defined name is a name, not an eta-reduced built-in,
68
+ * and stays bare. Asked as each formula is written, so an answer that reads the live names is
69
+ * about the names that save writes; a `Set` is a fixed answer.
51
70
  *
52
71
  * @remarks
53
72
  * Pure syntax + the measured `ExcelFunctionFacts` rows — the transform never consults the calc
@@ -55,16 +74,18 @@ export declare const XLOP = "_xlop.";
55
74
  * runs once per formula block on the compiled AST; formulas with nothing legacy in them return
56
75
  * every node untouched, which skips recompilation entirely.
57
76
  */
58
- export declare function createLegacyWriteTransform(definedNames?: ReadonlySet<string>): ICalculation.FormulaTransform;
77
+ export declare function createLegacyWriteTransform(definedNames?: {
78
+ has(name: string): boolean;
79
+ }): ICalculation.FormulaTransform;
59
80
  /**
60
81
  * The read direction: on-disk xlsx spellings → the modern (dynamic) tree, applied by the reader
61
- * at parse time (`IWorkbook.ConstructorOptions.formulaTransform`).
82
+ * at parse time (`ICellContainerOptions.getFormulaTransform`).
62
83
  *
63
84
  * @remarks
64
85
  * The mirror of {@link createLegacyWriteTransform}: strip `_xlfn._xlws.` BEFORE `_xlfn.`;
65
86
  * unwrap `SINGLE`/`ANCHORARRAY`/`_TRO_*` to their operators (matched on the bare name whether
66
- * or not a prefix was present — parity with the tolerance the parser used to have); strip
67
- * `_xleta.`/`_xlpm.` from names. `[#This Row]` → `@` needs nothing here — that spelling is
87
+ * or not a prefix was present — parity with the tolerance the parser used to have); join a
88
+ * `_LONGTEXT` call's chunks back into the one literal; strip `_xleta.`/`_xlpm.` from names. `[#This Row]` → `@` needs nothing here — that spelling is
68
89
  * valid TYPED input and the SDK normalizes it for every dialect.
69
90
  *
70
91
  * Load-path only: typed text never gets this pass, so `=_xlfn.SUM(A1)` typed is an unknown
@@ -1,12 +1,23 @@
1
1
  import { IWorkbookIO } from '@sheetxl/sdk';
2
2
  /**
3
- * The registry key both formats below share. Also the "same package family" test at the writer's
4
- * source-package seam (`XLSXWriter.ts`) — an origin only ever gets a retained `SourcePackage` by
5
- * successfully zip-parsing under {@link ReadFormat}'s handler, so this key alone is enough to tell
6
- * a genuine xlsx/xlsm round trip from a `.sxl`/`.csv` origin, without needing path/extension info a
7
- * server-side buffer read may not have. See `DESIGN-PACKAGE-PASSTHROUGH.md` §6.
3
+ * The registry key for Excel.
8
4
  */
9
5
  export declare const XLSX_FORMAT_KEY = "Excel";
6
+ /**
7
+ * The registry key for macro-enabled Excel (`.xlsm`).
8
+ *
9
+ * @remarks
10
+ * A separate registered format, not a second extension on {@link XLSX_FORMAT_KEY}: `DESIGN-IO.md`
11
+ * rejects one format owning several extensions precisely because the handler is never told which
12
+ * one is being written, and macro-enabledness is exactly such a per-extension decision. Both keys
13
+ * share one reader and one writer; only the *write* side is opinionated (the same shape `.sxl` and
14
+ * `.json` use).
15
+ *
16
+ * Splitting the **read** side too is what makes a plain save round-trip: an origin remembers the
17
+ * key it was read under, so an `.xlsm` opened as `Excel` would be saved back as `.xlsx` content
18
+ * under an `.xlsm` name.
19
+ */
20
+ export declare const XLSM_FORMAT_KEY = "ExcelMacro";
10
21
  /**
11
22
  * Registers all built-in read and write formats with the provided WorkbookIO registry.
12
23
  *
@@ -0,0 +1,38 @@
1
+ import { ISheetProtection, IWorkbookProtection } from '@sheetxl/sdk';
2
+ /**
3
+ * One protection attribute at the xlsx boundary.
4
+ *
5
+ * The model names what is ALLOWED (`true` = allowed); OOXML names what is PROTECTED (`"1"` = not
6
+ * allowed), so every value inverts on the way through. An omitted attribute is its `ooxmlDefault`
7
+ * (ECMA-376, confirmed against Excel), which is not the model's default: a bare
8
+ * `<sheetProtection sheet="1"/>` leaves objects and scenarios editable, while `lock()` with no
9
+ * options does not — Excel's own Protect Sheet writes `objects="1" scenarios="1"`.
10
+ */
11
+ export interface ProtectionAttribute<K extends string> {
12
+ /** The model property. */
13
+ key: K;
14
+ /** The OOXML attribute. */
15
+ attribute: string;
16
+ /** Whether the model allows it when the property is unset. */
17
+ modelDefault: boolean;
18
+ /** Whether the OOXML attribute PROTECTS it when omitted. */
19
+ ooxmlDefault: boolean;
20
+ }
21
+ /** `CT_SheetProtection`, in schema order. `showFormulas` has no attribute (formats carry it). */
22
+ export declare const SheetProtectionAttributes: readonly ProtectionAttribute<keyof ISheetProtection.JSON>[];
23
+ /**
24
+ * `CT_WorkbookProtection`'s lock flags. `revision` belongs to shared workbooks: nothing sets it, so an
25
+ * unset one writes nothing rather than locking revisions on every protected workbook.
26
+ */
27
+ export declare const WorkbookProtectionAttributes: readonly ProtectionAttribute<keyof IWorkbookProtection.Properties>[];
28
+ /**
29
+ * The model value for an attribute as read. An omitted or unparseable attribute reads as its OOXML
30
+ * default.
31
+ */
32
+ export declare const readProtectionAttribute: (spec: ProtectionAttribute<string>, value: string | null | undefined) => boolean;
33
+ /**
34
+ * The attribute value to write for a model value, or `null` when it equals the OOXML default and is
35
+ * omitted, as Excel does.
36
+ */
37
+ export declare const writeProtectionAttribute: (spec: ProtectionAttribute<string>, allowed: boolean | null | undefined) => "1" | "0" | null;
38
+ //# sourceMappingURL=ProtectionAttributes.d.ts.map
@@ -1,4 +1,4 @@
1
- import { IWorkbookIO } from '@sheetxl/sdk';
1
+ import { IWorkbook } from '@sheetxl/sdk';
2
2
  /**
3
3
  * The default upper bound, in decompressed bytes, on what a {@link SourcePackage} will retain.
4
4
  *
@@ -35,16 +35,33 @@ export interface SourcePackagePart {
35
35
  * @remarks
36
36
  * Not a residue map: this holds every non-streamed part from the source zip, decompressed. Which
37
37
  * of those a save actually copies through (vs. an emitter claiming the path, vs. a drop-bucket
38
- * rule) is decided at write time, not here.
38
+ * rule) is decided at write time, not here. The one thing it is told rather than holding is
39
+ * {@link isAbsorbed} — which parts the read put on the model, so the writer need not guess.
39
40
  */
40
41
  export declare class SourcePackage {
41
42
  private readonly _parts;
43
+ private readonly _absorbed;
42
44
  private readonly _totalBytes;
43
45
  private _structurallyChanged;
44
- constructor(parts: ReadonlyMap<string, SourcePackagePart>);
46
+ constructor(parts: ReadonlyMap<string, SourcePackagePart>, absorbed?: ReadonlySet<string> | null);
45
47
  getNames(): string[];
46
48
  has(name: string): boolean;
47
49
  getPart(name: string): SourcePackagePart | null;
50
+ /**
51
+ * Whether the reader took this part onto the model, so a save writes it from there rather than
52
+ * copying it through — see `DESIGN-PACKAGE-PASSTHROUGH.md` §4.
53
+ *
54
+ * @remarks
55
+ * Identity only: a name, never content. What each absorbed part *says* lives on the model that
56
+ * absorbed it (a chart's part on its movable, a sheet's VML on the sheet, a cache's definition on
57
+ * the workbook), which is the whole point of `PLAN-MODEL-HOMES.md` — this set exists so the
58
+ * passthrough can tell "the model owns this one" from "nothing modeled it" without a list of path
59
+ * patterns standing in for the answer.
60
+ *
61
+ * Independent of whether the element that cited the part still exists: deleting the chart deletes
62
+ * its part with it, and the source's copy should go too.
63
+ */
64
+ isAbsorbed(name: string): boolean;
48
65
  /** Sum of {@link SourcePackagePart.data}'s byte lengths across every retained part. */
49
66
  getTotalBytes(): number;
50
67
  /**
@@ -60,17 +77,19 @@ export declare class SourcePackage {
60
77
  hasStructuralChange(): boolean;
61
78
  markStructuralChange(): void;
62
79
  }
63
- /** The package retained for `origin`, or `null` if none was retained (or `origin` is unset). */
64
- export declare function getSourcePackage(origin: IWorkbookIO.Origin | null | undefined): SourcePackage | null;
80
+ /** The package retained for `workbook`, or `null` if none was retained. */
81
+ export declare function getSourcePackage(workbook: IWorkbook | null | undefined): SourcePackage | null;
65
82
  /**
66
- * Retain `sourcePackage` for `origin`, replacing anything previously retained for it.
83
+ * Retain `sourcePackage` for `workbook`, replacing anything previously retained for it.
67
84
  *
68
85
  * @remarks
69
- * Owned entirely by io-xlsx — the origin never learns this exists (no sdk change). Lifetime
70
- * follows the origin: stable across a save, fresh (and empty) for a copy or a new workbook, and
71
- * released via {@link releaseSourcePackage} on `IWorkbook.close()`.
86
+ * Owned entirely by io-xlsx — the workbook never learns this exists (no sdk change). Keyed by the
87
+ * WORKBOOK, not its origin: the parts belong to the model that was read, and pass through on every
88
+ * save of it wherever it is written — a Save As moves the workbook to a new origin, and the parts go
89
+ * with it. Fresh (and empty) for a copy or a new workbook; released via
90
+ * {@link releaseSourcePackage} on `IWorkbook.close()`.
72
91
  */
73
- export declare function setSourcePackage(origin: IWorkbookIO.Origin, sourcePackage: SourcePackage): void;
74
- /** Release whatever is retained for `origin`, if anything. Safe to call unconditionally. */
75
- export declare function releaseSourcePackage(origin: IWorkbookIO.Origin | null | undefined): void;
92
+ export declare function setSourcePackage(workbook: IWorkbook, sourcePackage: SourcePackage): void;
93
+ /** Release whatever is retained for `workbook`, if anything. Safe to call unconditionally. */
94
+ export declare function releaseSourcePackage(workbook: IWorkbook | null | undefined): void;
76
95
  //# sourceMappingURL=SourcePackage.d.ts.map
@@ -5,6 +5,23 @@ import { ReaderProfiler } from './reader/ReaderProfiler';
5
5
  * Options for exporting to XLSX file format.
6
6
  */
7
7
  export interface WriteXLSXOptions extends IWorkbookIO.WriteOptions {
8
+ /**
9
+ * Whether to write a macro-enabled workbook (`.xlsm`) rather than a plain one (`.xlsx`).
10
+ *
11
+ * @defaultValue false
12
+ *
13
+ * @remarks
14
+ * Set by the format registration, not by callers: `.xlsx` and `.xlsm` are two registered write
15
+ * formats sharing this one handler, which is how `DESIGN-IO.md` says a per-extension encoding
16
+ * decision must be expressed — a single format listing both extensions could not, because the
17
+ * handler is never told which of its extensions is being written.
18
+ *
19
+ * It decides **both halves together**, so the declaration can never disagree with the payload:
20
+ * the `xl/workbook.xml` content type, and whether a source package's `xl/vbaProject.bin` is
21
+ * carried through. Writing a macro workbook to `.xlsx` therefore drops the VBA project, which is
22
+ * what Excel's own *Save As* does.
23
+ */
24
+ macroEnabled?: boolean;
8
25
  /**
9
26
  * Callback invoked when a part is emitted.
10
27
  *
@@ -0,0 +1,16 @@
1
+ import { IWorkbook } from '@sheetxl/sdk';
2
+ /** The `paramMap` key under which the styles part leaves its `hidden="1"` cell xf indices. */
3
+ export declare const HIDDEN_XFS_PARAM = "hiddenXfs";
4
+ /**
5
+ * Turns xlsx's per-format `hidden` into the model's sheet `showFormulas` plus per-format grants.
6
+ *
7
+ * A formula shows when the sheet OR its format allows it; xlsx only has the format's `hidden`. So a
8
+ * sheet that uses any hidden format reads as `showFormulas: false` (an unprotected one keeping it as
9
+ * `sheet: true` protection), and every format it uses
10
+ * without `hidden="1"` is granted `showFormulas: true`. The formats are counted from the merged style
11
+ * references (cells, rows, columns, and xf 0 unless columns style everything), never per cell. xf 0 is Normal, so
12
+ * its grant goes on the Normal style, and the hidden formats say `false` outright rather than inherit
13
+ * it.
14
+ */
15
+ export declare const applyHiddenFormulas: (jsonWB: IWorkbook.JSON, hiddenXfs: ReadonlySet<number> | undefined) => void;
16
+ //# sourceMappingURL=HiddenFormulas.d.ts.map
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The sink a reader hands to everything it reads a part with.
3
+ *
4
+ * @remarks
5
+ * Load warnings belong to the host, which decides whether to show them — the CLI, for one, gates
6
+ * them on its log level. A warning written straight to the console has left that channel and
7
+ * cannot be silenced, so every transform a reader runs is given one of these.
8
+ *
9
+ * `context` locates the finding (the OPC path of the part, plus a sheet path where there is one).
10
+ * `onceKey` is {@link WarningOptions.onceKey}, carried from the emit site.
11
+ */
12
+ export type OnWarning = (message: string, context?: string, onceKey?: string) => void;
13
+ /** What an emit site may say about the warning it is raising, beyond its text. */
14
+ export interface WarningOptions {
15
+ /**
16
+ * Reports only the first warning carrying this key, for one read.
17
+ *
18
+ * @remarks
19
+ * Whether a warning means "this kind of thing, once" or "this specific thing" is known only
20
+ * where it is raised, so the key is the emit site's to give: a finding that names the shape it
21
+ * found is one per shape without a key, and one per file with one.
22
+ *
23
+ * Keys are stable dotted identifiers owned by this package, such as `xlsx.drawing.fixedShape`.
24
+ * Never derive one from the message text — rewording or localizing a message must not change
25
+ * what collapses. The first occurrence is the one reported, message and context both.
26
+ */
27
+ onceKey?: string;
28
+ }
29
+ //# sourceMappingURL=Warning.d.ts.map
@@ -22,7 +22,7 @@ export declare class DOMTransformer {
22
22
  * the `dxfs` table, so it arrives from the streaming reader with no index to look up. The
23
23
  * `processingDXFs` flag matters: a dxf's solid pattern fill has its colors inverted.
24
24
  */
25
- parseDxf(elem: Element, location?: string): IStyle.JSON;
25
+ parseDxf(elem: Element, location?: string, options?: TransformerOptions): IStyle.JSON;
26
26
  getVisitorParamsState(): Map<string, any>;
27
27
  transform(xmlRootDoc: Document, location: string, options?: TransformerOptions): any;
28
28
  protected _walkScoped(elemName: string, context: ExecutionContext, visited: VisitedRecord[], elemParent: Element, jsonParent: any, location: string, options: TransformerOptions): void;
@@ -1,4 +1,5 @@
1
- import { IComment } from '@sheetxl/sdk';
1
+ import { IPerson, IEmbeddedPart } from '@sheetxl/sdk';
2
+ import { WarningOptions } from '../Warning';
2
3
  import { RelationShipType, TransformerOptions } from './Types';
3
4
  export interface VisitorParamsContainer {
4
5
  getVisitorParamsState(): Map<string, any>;
@@ -22,18 +23,30 @@ export declare class ExecutionContext {
22
23
  private _onWarning?;
23
24
  private _addPerson?;
24
25
  private _serializeElement?;
26
+ private _readEmbeddedPart?;
25
27
  constructor(parent: ExecutionContext | null, sharedState: VisitorParamsContainer, currentPath: string, elemRoot: Element, jsonRoot: any, fileLocation?: string | null, options?: TransformerOptions);
26
28
  getRef(relId: string, asResource?: boolean): any;
29
+ /**
30
+ * The part this relationship names, and every part that part references, as one carried subtree.
31
+ *
32
+ * @remarks
33
+ * Not a flavor of {@link ExecutionContext.getRef}: that one interprets a relationship into
34
+ * whatever the reader models its target as, this one carries the target away unread so a writer
35
+ * can put it back. See {@link TransformerOptions.readEmbeddedPart}.
36
+ */
37
+ readEmbeddedPart(relId: string): IEmbeddedPart.JSON | null;
27
38
  getRelationships(): Map<string, RelationShipType>;
28
39
  getPath(): string;
29
40
  /** The OPC path of the file currently being read (e.g. "xl/drawings/drawing1.xml"). */
30
41
  getFileLocation(): string;
31
42
  getElemRoot(): Element;
32
43
  getJsonRoot(): any;
33
- warn(message: string): void;
44
+ warn(message: string, options?: WarningOptions): void;
45
+ /** Carries the originating part's path up to whichever context holds the sink. */
46
+ private _raiseWarning;
34
47
  /** Serializes a parsed DOM element back to an XML string, verbatim. Returns null if unavailable. */
35
48
  serializeElement(elem: Element): string | null;
36
- addPerson(person: string | Partial<IComment.PersonJSON>): IComment.PersonJSON | null;
49
+ addPerson(person: string | Partial<IPerson.JSON>): IPerson.JSON | null;
37
50
  getVisitorParamsState<T = any>(): Map<string, T>;
38
51
  /**
39
52
  * Evaluates a path expression against an XML element and returns matching elements.