@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.
- package/browser/cjs/BzOEBR0jaxXg9wvt.cjs +5 -0
- package/browser/cjs/C8oC1tPbhgR0Dqtx.cjs +2 -0
- package/browser/cjs/Ca-xJDjg5bOpUPXX.cjs +1 -0
- package/browser/cjs/{D5Y4KQhKdukOkjvA.cjs → D3EWCPfCu-qMOIGd.cjs} +1 -2
- package/browser/cjs/{DK9GutW2zPbyNlfU.cjs → DULsYP_GcPGLVYSE.cjs} +10 -1
- package/browser/cjs/DtBN3UOzNJjYBwJ6.cjs +1 -0
- package/browser/cjs/index.cjs +1 -1
- package/browser/cjs/sNZR19Wk-XQ2xZ9E.cjs +1 -0
- package/browser/esm/B9q618XELV7uWJsA.mjs +67 -0
- package/browser/esm/{D8qZcXzj_fdusd0Y.mjs → BwbMurFOptAFs7gC.mjs} +1596 -1130
- package/browser/esm/{BhohPLTubb_9rfrh.mjs → CMHb6pUUmsCP9r_9.mjs} +2 -2
- package/browser/esm/{saBnxecsRUpY6fGv.mjs → CMzkLUwbgA73RvCb.mjs} +1 -1
- package/browser/esm/D75_rfogFUfXADKc.mjs +3324 -0
- package/browser/esm/{DlBlJGlFQJrKovwJ.mjs → DfuBawaydlvgZMR-.mjs} +1827 -1050
- package/browser/esm/{BknJ4AeVeFJploh9.mjs → DhqYgh9G2vLn7mIE.mjs} +28 -13
- package/browser/esm/DoMlKUCnMSlR2qX5.mjs +159 -0
- package/browser/esm/{CV_L3E5OoPstI9lx.mjs → DtpWa7tZahylJ3HS.mjs} +446 -347
- package/browser/esm/{BXCOn1XvLvYSfpzi.mjs → IZf0hIeLYj3T0Xvu.mjs} +2 -2
- package/browser/esm/{C3sYFBc7Tym8l12A.mjs → _UDbQq5-pHbU1f82.mjs} +1 -1
- package/browser/esm/index.mjs +3 -3
- package/node/esm/{DsZ19z4oXoL-d0Lk.mjs → BD03jrMQ_UKA196-.mjs} +1937 -1142
- package/node/esm/{B6lQXVQjFT_OE3IA.mjs → Bi_kZVtZams7taqa.mjs} +2 -2
- package/node/esm/{BYCpXFieBgL_cwTO.mjs → BxHvzSROx_N_7nJH.mjs} +607 -506
- package/node/esm/{CfIzBnObj09fDuUX.mjs → CB1ijGbhl-e2l6Mm.mjs} +49 -35
- package/node/esm/CO1M1H1N6fB422K-.mjs +2959 -0
- package/node/esm/CWpezSa6TERGEv-B.mjs +3410 -0
- package/node/esm/{B9CUp-rqol5K1r1c.mjs → CY-pSutJLHskZfXZ.mjs} +1 -1
- package/node/esm/Dezt2uIDqlxjiuk5.mjs +170 -0
- package/node/esm/index.mjs +40 -25
- package/package.json +3 -3
- package/types/src/ConditionalFormatRules.d.ts +3 -3
- package/types/src/DataValidationRules.d.ts +18 -2
- package/types/src/ExcelCalcStamp.d.ts +39 -0
- package/types/src/ExcelCompat.d.ts +197 -42
- package/types/src/LegacyFormula.d.ts +28 -7
- package/types/src/Plugin.d.ts +16 -5
- package/types/src/ProtectionAttributes.d.ts +38 -0
- package/types/src/SourcePackage.d.ts +31 -12
- package/types/src/Types.d.ts +17 -0
- package/types/src/reader/HiddenFormulas.d.ts +16 -0
- package/types/src/reader/Warning.d.ts +29 -0
- package/types/src/reader/dom/DOMTransformer.d.ts +1 -1
- package/types/src/reader/dom/ExecutionContext.d.ts +16 -3
- package/types/src/reader/dom/Types.d.ts +19 -3
- package/types/src/reader/domVisitors/CommentVisitor.d.ts +18 -1
- package/types/src/reader/domVisitors/CommentsVisitor.d.ts +2 -2
- package/types/src/reader/domVisitors/ExternalLinkVisitor.d.ts +21 -3
- package/types/src/reader/domVisitors/SheetColorContainerVisitor.d.ts +2 -2
- package/types/src/reader/domVisitors/SheetStyleVisitor.d.ts +6 -1
- package/types/src/reader/domVisitors/ThreadedCommentVisitor.d.ts +9 -1
- package/types/src/reader/domVisitors/ThreadedCommentsVisitor.d.ts +2 -2
- package/types/src/reader/domVisitors/WorkbookVisitor.d.ts +11 -1
- package/types/src/reader/sax/LeanSaxParser.d.ts +58 -0
- package/types/src/reader/sax/SaxParser.d.ts +11 -1
- package/types/src/reader/sax/SaxVisitor.d.ts +3 -2
- package/types/src/reader/saxVisitors/ContentTypesVisitor.d.ts +9 -0
- package/types/src/reader/saxVisitors/WorksheetVisitor.d.ts +11 -4
- package/types/src/utils/VmlNoteShapes.d.ts +75 -0
- package/types/src/vba/VBAProject.d.ts +52 -4
- package/types/src/writer/builder/ContentTypes.d.ts +13 -0
- package/types/src/writer/builder/Emitter.d.ts +6 -6
- package/types/src/writer/builder/EmitterRegistry.d.ts +7 -0
- package/types/src/writer/builder/OpcXmlUtils.d.ts +2 -0
- package/types/src/writer/builder/PackageBuilder.d.ts +70 -22
- package/types/src/writer/builder/PartWriter.d.ts +5 -0
- package/types/src/writer/builder/RelationshipSet.d.ts +3 -0
- package/types/src/writer/builder/Types.d.ts +107 -38
- package/types/src/writer/builder/_Types.d.ts +17 -0
- package/types/src/writer/emitters/CommentsEmitter.d.ts +52 -0
- package/types/src/writer/emitters/EmbeddedPartEmitter.d.ts +60 -0
- package/types/src/writer/emitters/ExternalLinkEmitter.d.ts +19 -0
- package/types/src/writer/emitters/LegacyDrawingEmitter.d.ts +18 -0
- package/types/src/writer/emitters/PersonsEmitter.d.ts +17 -0
- package/types/src/writer/emitters/PivotTableEmitter.d.ts +45 -0
- package/types/src/writer/emitters/ThreadedCommentsEmitter.d.ts +21 -0
- package/types/src/writer/emitters/WorkbookEmitter.d.ts +16 -3
- package/types/src/writer/utils/DrawMLUtils.d.ts +16 -1
- package/types/src/writer/utils/HiddenFormulaXfs.d.ts +28 -0
- package/browser/cjs/Bhq8KfEhCnRykWeS.cjs +0 -1
- package/browser/cjs/BmG0GOcbuYvt3-R2.cjs +0 -1
- package/browser/cjs/D3YH3tTndeltJsh5.cjs +0 -1
- package/browser/cjs/DWkuoJSgvcXJTdN1.cjs +0 -1
- package/browser/cjs/Dmi-Tsz618B6vKpZ.cjs +0 -5
- package/browser/esm/BcnofzmeeuCVzr_M.mjs +0 -52
- package/browser/esm/C7R1lFA0iv-1bZ9i.mjs +0 -99
- package/browser/esm/DLEtaZiz_1cZH0dA.mjs +0 -2685
- package/node/esm/BSrW-J3BEH4Tza_S.mjs +0 -2486
- package/node/esm/Bqi4c7-14v0oNgFN.mjs +0 -108
- 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
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
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},
|
|
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
|
|
66
|
-
getFunction(name: string):
|
|
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
|
|
132
|
-
*
|
|
133
|
-
*
|
|
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
|
-
*
|
|
137
|
-
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
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
|
|
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}
|
|
64
|
+
* {@link ICalculation.FormulaTransform} — the `write` half of the xlsx dialect (`ExcelCompat`).
|
|
48
65
|
*
|
|
49
|
-
* @param definedNames
|
|
50
|
-
* resolves to a REAL defined name is a name, not an eta-reduced built-in,
|
|
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?:
|
|
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 (`
|
|
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);
|
|
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
|
package/types/src/Plugin.d.ts
CHANGED
|
@@ -1,12 +1,23 @@
|
|
|
1
1
|
import { IWorkbookIO } from '@sheetxl/sdk';
|
|
2
2
|
/**
|
|
3
|
-
* The registry key
|
|
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 {
|
|
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 `
|
|
64
|
-
export declare function getSourcePackage(
|
|
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 `
|
|
83
|
+
* Retain `sourcePackage` for `workbook`, replacing anything previously retained for it.
|
|
67
84
|
*
|
|
68
85
|
* @remarks
|
|
69
|
-
* Owned entirely by io-xlsx — the
|
|
70
|
-
*
|
|
71
|
-
*
|
|
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(
|
|
74
|
-
/** Release whatever is retained for `
|
|
75
|
-
export declare function releaseSourcePackage(
|
|
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
|
package/types/src/Types.d.ts
CHANGED
|
@@ -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 {
|
|
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<
|
|
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.
|