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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/browser/esm/{9dwUocbOsJuAcmKn.mjs → BjkdoGjLpkKUlK5q.mjs} +2234 -2250
  2. package/browser/esm/{DeMZN_qj__PKo4Wh.mjs → Bomb4K5f16UyiyED.mjs} +1 -1
  3. package/browser/esm/{D8k22TSWPd_RHEpj.mjs → Bs0IJqyry5ZycCBU.mjs} +988 -1008
  4. package/browser/esm/CIRY1QIACITHu_lA.mjs +24 -0
  5. package/browser/esm/{DVLJTjJCGqrJUa8c.mjs → Cs4lg7bxClbTkldF.mjs} +61 -61
  6. package/browser/esm/{aUBXbTh2r0u3x4Xo.mjs → DAYdoS9sLmYf8kzD.mjs} +2 -2
  7. package/browser/esm/{BIvDjK4Zl8bWRgl8.mjs → DKWU_JYjVmtOzTGr.mjs} +2 -2
  8. package/browser/esm/{DsppUz-14Z7ti9i3.mjs → DN7ig6HovGU5gMbr.mjs} +1 -1
  9. package/browser/esm/{CcH5ITJFTMVWUJO9.mjs → DbygDdjktfjoU4DI.mjs} +1041 -1041
  10. package/browser/esm/{DO75RoAQTgMuVzXv.mjs → DiNNY0EgHikWbrDz.mjs} +2 -2
  11. package/browser/esm/{DKnOwucZq4z9_-r-.mjs → QuYxg3ec6kN-djPF.mjs} +4 -4
  12. package/browser/esm/index.mjs +2 -2
  13. package/node/esm/{C78E45n6j2E8rruH.mjs → BCSJ_kqVLXkZlYh3.mjs} +818 -819
  14. package/node/esm/{DXusvwW73FUDSyvD.mjs → BCXSNXHvNQ9JQMLE.mjs} +1129 -1129
  15. package/node/esm/{DsyuWxk3bdGhJUQN.mjs → BycDf9HTtfpzL-zt.mjs} +1 -1
  16. package/node/esm/{BmIIQODk4dBVIXA4.mjs → CTdvEKRTM-W1L1KU.mjs} +976 -994
  17. package/node/esm/{DCaAOfuW-w_dx_qd.mjs → CkenuXqno-ffP331.mjs} +2 -2
  18. package/node/esm/{CDKm5s3JE_d99TJw.mjs → CvcAx132Yp5uUDUB.mjs} +81 -81
  19. package/node/esm/{C-e5AO_4TnGywT-m.mjs → H9egT6kWCw8RAf76.mjs} +1 -1
  20. package/node/esm/{DSgxL0sBZtWMydVl.mjs → TPq4Re0SQgONsX_u.mjs} +2 -2
  21. package/node/esm/index.mjs +4 -4
  22. package/package.json +3 -3
  23. package/types/src/AutoFilterRules.d.ts +0 -42
  24. package/types/src/DataTableFormula.d.ts +0 -10
  25. package/types/src/DataValidationRules.d.ts +0 -5
  26. package/types/src/ExcelCalcStamp.d.ts +0 -36
  27. package/types/src/ExcelCompat.d.ts +0 -140
  28. package/types/src/ExcelFunctionFacts.d.ts +0 -272
  29. package/types/src/ExcelReservedNames.d.ts +0 -64
  30. package/types/src/KnownFonts.d.ts +0 -13
  31. package/types/src/LegacyFormula.d.ts +0 -58
  32. package/types/src/Plugin.d.ts +3 -3
  33. package/types/src/SheetKinds.d.ts +0 -15
  34. package/types/src/SourcePackage.d.ts +0 -44
  35. package/types/src/Types.d.ts +2 -3
  36. package/types/src/chart/_chartExStyle.d.ts +0 -9
  37. package/types/src/reader/DummyFunctionUnwrap.d.ts +43 -23
  38. package/types/src/reader/domVisitors/AutoFilterVisitor.d.ts +0 -8
  39. package/types/src/reader/domVisitors/ExternalLinkVisitor.d.ts +0 -10
  40. package/types/src/reader/domVisitors/FeaturePropertyBagVisitor.d.ts +0 -9
  41. package/types/src/reader/domVisitors/FmtSchemeVisitor.d.ts +0 -11
  42. package/types/src/reader/domVisitors/WorkbookVisitor.d.ts +0 -9
  43. package/types/src/reader/saxVisitors/SharedStringsVisitor.d.ts +0 -15
  44. package/types/src/reader/saxVisitors/WorksheetVisitor.d.ts +3 -1
  45. package/types/src/richValue/WebImageRichValueHandler.d.ts +0 -5
  46. package/types/src/utils/VmlNoteStyle.d.ts +0 -19
  47. package/types/src/vba/VBAProject.d.ts +0 -19
  48. package/types/src/writer/builder/OpcXmlUtils.d.ts +0 -8
  49. package/types/src/writer/builder/PackageBuilder.d.ts +0 -41
  50. package/types/src/writer/builder/Types.d.ts +0 -30
  51. package/types/src/writer/emitters/ExternalLinkEmitter.d.ts +0 -11
  52. package/types/src/writer/emitters/FeaturePropertyBagEmitter.d.ts +0 -10
  53. package/types/src/writer/utils/DefaultRows.d.ts +0 -16
  54. package/types/src/writer/utils/DummyFunction.d.ts +0 -23
@@ -1,66 +1,2 @@
1
- /**
2
- * Names Excel REFUSES in a worksheet formula, at every arity — the XLM macro-sheet heritage.
3
- *
4
- * Emitting one of these bare is not a `#NAME?`, it is an xlsx Excel will not open: the normal
5
- * load is refused outright, and a user who clicks through the repair prompt gets the workbook
6
- * back with the offending cell EMPTIED — formula and cached value both gone, and nothing marking
7
- * that anything was ever there. Measured with its repair outcome in
8
- * `spreadsheetbench/formula-tests/probe-reserved-name-load.ps1/.json`. The `_xlfn.` marker does
9
- * NOT rescue them.
10
- *
11
- * This is the third of the export hazards and the only one that is file-fatal. The other two:
12
- *
13
- * - `ExcelFunctionFact.unimplemented` — Excel has the name, we do not. Record its spelling so
14
- * the `_xlfn.` prefix survives the round trip.
15
- * - the deny-set (descriptor category `Sheets`/`SheetXL`, pinned by
16
- * `sdk/src/__tests__/calculation/excelSupported.parity.test.ts`) — we have the name, Excel does
17
- * not. Wrap it so the VALUE survives; bare would cost the user their answer.
18
- * - here — neither has it as a worksheet function AND Excel reserves the name. Wrap it so the
19
- * FILE survives.
20
- *
21
- * ### Provenance
22
- *
23
- * Candidates come from two sources: MS-XLSX §2.2.2 `command-list` + `ref-macro-function-call` +
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
27
- * MS-XLSX production and fatal in a worksheet cell.
28
- *
29
- * Membership in either source is NOT the verdict — `FILTER`, `IF` and `SORT` appear in them and
30
- * are ordinary worksheet functions — so every name was MEASURED by entry
31
- * (`probe-reserved-name-sweep.ps1/.json`, 2026-08-15, Excel 16.0 build 20228): 504 of the 1,238
32
- * candidates are refused at every arity from 0 to 12.
33
- *
34
- * Trying EVERY arity is what makes the reading clean. Excel arity-checks only a name it
35
- * recognizes, so an unknown name enters at arity 0 (it is read as a call to a defined name that
36
- * does not exist) while a real function enters at its own minimum — `XLOOKUP` at 3, `ACCRINT`
37
- * at 6, `ODDFPRICE` at 8. Refused at all of them means the NAME was rejected, not the argument
38
- * count. The range has to reach the largest mandatory arity in Excel or real functions look
39
- * reserved: a 0..4 range condemned `ACCRINT`, `PRICE`, `YIELD`, `DURATION`, `VDB` and the
40
- * `ODD*` family, which is why the probe now carries high-arity controls and fails outright if a
41
- * name our own registry implements measures reserved.
42
- *
43
- * ### What is deliberately NOT here
44
- *
45
- * A name we never emit BARE cannot be reached by this hazard, and listing it would do harm.
46
- * `ANCHORARRAY` and `PQSOURCE` are both refused bare, but `ExcelFunctionFacts` gives them an
47
- * `_xlfn.` prefix, so we write `_xlfn.PQSOURCE(…)` — the spelling Excel itself writes. Wrapping
48
- * them would replace a correct round trip with a dead `DUMMYFUNCTION` value, defeating the
49
- * `unimplemented` rows that exist to preserve exactly that. The rule: a measured refusal earns
50
- * a place here only if the facts map gives the name no prefix. Lint join 6 enforces it.
51
- *
52
- * Only `SPLIT` and `WAIT` are also in our own registry, and the deny-set already wraps both. The
53
- * rest matter because they reach `resolveUnsupported` as names we do not know, where the default
54
- * is to pass them through untouched.
55
- *
56
- * ### The one name here that measured WRITABLE
57
- *
58
- * `MSOCHECKS` enters at every arity on build 20228 — this Excel has forgotten it, so it behaves
59
- * like any other unknown name. It is listed anyway, against the measurement, because the two
60
- * errors are not symmetric: a build that still remembers the name makes it file-fatal, while a
61
- * false positive costs one dead formula in a name nobody types. `FILTER`, `IF` and `SORT` also
62
- * measured writable and are NOT listed — those are live worksheet functions, where wrapping
63
- * would break working formulas.
64
- */
65
1
  export declare const ExcelReservedNames: ReadonlySet<string>;
66
2
  //# sourceMappingURL=ExcelReservedNames.d.ts.map
@@ -1,17 +1,4 @@
1
1
  import { IFontCollection } from '@sheetxl/sdk';
2
- /**
3
- * `x14ac:knownFonts` on `<fonts>` in `styles.xml`: whether a workbook's stored row heights were
4
- * measured with the real fonts.
5
- *
6
- * Excel's rule, from `private-assets/design/rust/tools/oracle-excel-knownfonts.ps1` (2026-10-16):
7
- * it writes the flag only when it knows every font in the file, and on open it keeps the stored
8
- * heights of rows that are not custom only when the file has the flag, the Normal style's font is
9
- * a theme font (`<scheme>`, as in every new workbook; one named outright is re-fitted whatever the
10
- * flag says), and it knows every font itself; otherwise it re-fits those rows. Which font it is
11
- * does not matter (Calibri, Arial and Aptos alike). Knowing a font, here, is measuring it with a
12
- * table of its own: a shipped or added table, or an installed face, never a related family or a
13
- * stand-in.
14
- */
15
2
  /** The `paramMap` key under which the styles part leaves what it read about its fonts. */
16
3
  export declare const KNOWN_FONTS_PARAM = "knownFonts";
17
4
  /** One face a workbook's fonts name. */
@@ -1,49 +1,8 @@
1
1
  import { ICalculation } from '@sheetxl/sdk';
2
2
  export { XLFN, XLWS } from './ExcelFunctionFacts';
3
- /**
4
- * The xlsx legacy-formula dialect — every version-compatibility SPELLING between the modern
5
- * (dynamic) formula language and what Excel stores on disk. Shared by the writer and the reader;
6
- * the round-trip tests in this package are the contract that the two halves stay in step.
7
- *
8
- * All of it is measured tables + structural rewrites (DESIGN-FORMULA-DIALECT.md):
9
- *
10
- * | construct | modern (tree) | on disk (xlsx) |
11
- * | --- | --- | --- |
12
- * | future functions | `XLOOKUP(...)` | `_xlfn.XLOOKUP(...)` |
13
- * | worksheet-only | `FILTER(...)` | `_xlfn._xlws.FILTER(...)` |
14
- * | spill anchor | postfix `#` | `_xlfn.ANCHORARRAY(ref)` |
15
- * | implicit intersection | prefix `@` | `_xlfn.SINGLE(ref)` (unless in a table reference) |
16
- * | structured this-row | `@col` in a table ref | `[#This Row],[col]` |
17
- * | trim-range | infix `.:.` / `.:` / `:.` | `_xlfn._TRO_ALL/_TRO_LEADING/_TRO_TRAILING(a:b)` |
18
- * | bare built-in | named `SUM` (unresolved) | `_xleta.SUM` — from the MEASURED `ExcelFunctionFacts` map |
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…",…)` |
21
- *
22
- * MS-XLSX Extensions to Office Open XML section 2.2.2 Formula:
23
- * https://learn.microsoft.com/en-us/openspecs/office_standards/ms-xlsx/3d025add-118d-4413-9856-ab65712ec1b0
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
3
  export declare const LONGTEXT = "_LONGTEXT";
39
4
  /** The longest string literal Excel spells bare — see {@link LONGTEXT}. */
40
5
  export declare const LONGTEXT_CHUNK = 255;
41
- /**
42
- * Eta-reduced-lambda prefix — a BUILT-IN function referenced WITHOUT parentheses
43
- * (`=BYROW(A1:B3,SUM)`, and equally `=SUM(ABS)` or `=1+ABS`: Excel prefixes it wherever it
44
- * appears, not only in lambda-taking slots). A user-defined name (bound to LAMBDA) stays bare.
45
- * Measured: `spreadsheetbench/formula-tests/probe-xleta*.ps1`, `probe-bare-name.ps1`.
46
- */
47
6
  export declare const XLETA = "_xleta.";
48
7
  /**
49
8
  * Lambda-parameter prefix (`_xlpm.name`), stripped on read.
@@ -53,24 +12,7 @@ export declare const XLETA = "_xleta.";
53
12
  * cell holds a literal `#NAME?`. See {@link _prefixScopeParameters}.
54
13
  */
55
14
  export declare const XLPM = "_xlpm.";
56
- /**
57
- * Optional-parameter prefix (`_xlop.name`) — the DECLARATION spelling of `[b]`; every use of the
58
- * parameter stays `_xlpm.` (measured, application §2.6). Read restores the flag, not the brackets:
59
- * the display form re-images from `NamedRef.optional`.
60
- */
61
15
  export declare const XLOP = "_xlop.";
62
- /**
63
- * User-defined-function prefix (`_xludf.name`): a call to a function Excel does not resolve.
64
- *
65
- * Excel writes it on a name that would otherwise read as one of its own functions. Measured
66
- * (`spreadsheetbench/formula-tests/probe-bare-future-function.ps1`, Excel 16.0, 2026-10-19): a
67
- * function Excel stores with a prefix (`_xlfn.RRI`), stored BARE (`<f>RRI(A1,B1,C1)</f>`, as
68
- * openpyxl and other non-Excel writers leave it), is read as a call to an unknown function -
69
- * `=@RRI(A1,B1,C1)`, `#NAME?` - and saved untouched as `_xludf.RRI(A1,B1,C1)`; only re-entering
70
- * the formula makes it the real `RRI`. The bare and the `_xludf.` spellings are the same formula to
71
- * Excel, so the model holds both as `_xludf.RRI` and writes it bare: LibreOffice keeps whichever
72
- * spelling it is given, and the bare one is what every other producer wrote.
73
- */
74
16
  export declare const XLUDF = "_xludf.";
75
17
  /**
76
18
  * The write direction: modern (dynamic) tree → on-disk xlsx spellings, as an
@@ -7,9 +7,9 @@ export declare const XLSX_FORMAT_KEY = "Excel";
7
7
  * The registry key for macro-enabled Excel (`.xlsm`).
8
8
  *
9
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
10
+ * A separate registered format, not a second extension on {@link XLSX_FORMAT_KEY}: a format's
11
+ * handler is never told which of its extensions is being written, and macro-enabledness is exactly
12
+ * such a per-extension decision. Both keys
13
13
  * share one reader and one writer; only the *write* side is opinionated (the same shape `.sxl` and
14
14
  * `.json` use).
15
15
  *
@@ -27,22 +27,7 @@ export declare const readTabColorAttributes: (xml: string) => Map<string, string
27
27
  * the root, so that is where each goes when absent.
28
28
  */
29
29
  export declare const patchTabColor: (xml: string, tabColorXml: string | null) => string;
30
- /**
31
- * The part with its first `sheetView@tabSelected` saying whether the tab is selected.
32
- *
33
- * @remarks
34
- * A carried part keeps the source's flag, and Excel group-selects every sheet that has it on open
35
- * (`probe-sheet-kinds-open.ps1`), so a stale one has to go.
36
- */
37
30
  export declare const patchTabSelected: (xml: string, selected: boolean) => string;
38
- /**
39
- * A macro sheet's part as a worksheet's: the root renamed, the body unchanged.
40
- *
41
- * @remarks
42
- * What Excel does saving a macro sheet into a workbook that cannot hold one (`.xlsx`): the tab comes
43
- * back as a worksheet holding the same cells (`probe-sheet-kinds-open.ps1`). The macro sheet's body
44
- * is a worksheet's, element for element in the same order, so only the root changes.
45
- */
46
31
  export declare const macroSheetAsWorksheet: (xml: string) => string;
47
32
  /**
48
33
  * A macro sheet's part made independent of the workbook parts it cites by position: each shared
@@ -1,13 +1,4 @@
1
1
  import { IWorkbook } from '@sheetxl/sdk';
2
- /**
3
- * The default upper bound, in decompressed bytes, on what a {@link SourcePackage} will retain.
4
- *
5
- * @remarks
6
- * Applies to the retained parts only — worksheet/chartsheet bodies and shared strings are never
7
- * retained (they are always model-owned and rewritten on every save), so this is not the file's
8
- * uncompressed size, just the "side parts" (styles, drawings, media, printer settings, …) that
9
- * would otherwise be copied through untouched. See `DESIGN-PACKAGE-PASSTHROUGH.md`.
10
- */
11
2
  export declare const SOURCE_PACKAGE_MAX_BYTES: number;
12
3
  /**
13
4
  * A part's still-compressed bytes, sliced directly out of the source zip's local file header —
@@ -27,17 +18,6 @@ export interface SourcePackagePart {
27
18
  /** Present when the source's compressed bytes could be sliced out directly; see {@link SourcePackageRawPart}. */
28
19
  readonly raw?: SourcePackageRawPart;
29
20
  }
30
- /**
31
- * The parts of a source OOXML package that SheetXL read but does not model — retained verbatim so
32
- * a save can pass them through instead of silently dropping them. See
33
- * `DESIGN-PACKAGE-PASSTHROUGH.md`.
34
- *
35
- * @remarks
36
- * Not a residue map: this holds every non-streamed part from the source zip, decompressed. Which
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. 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.
40
- */
41
21
  export declare class SourcePackage {
42
22
  private readonly _parts;
43
23
  private readonly _absorbed;
@@ -47,33 +27,9 @@ export declare class SourcePackage {
47
27
  getNames(): string[];
48
28
  has(name: string): boolean;
49
29
  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
30
  isAbsorbed(name: string): boolean;
65
31
  /** Sum of {@link SourcePackagePart.data}'s byte lengths across every retained part. */
66
32
  getTotalBytes(): number;
67
- /**
68
- * A one-way latch: once true, stays true for this package's lifetime (i.e. until the origin is
69
- * closed and a fresh read replaces it). Set by the reader when it detects a structural edit —
70
- * sheet add/delete/reorder, row/column insert/delete — since the read that produced this package.
71
- *
72
- * @remarks
73
- * Deliberately never resets on an undo: an undo doesn't guarantee the exact original XML-level
74
- * geometry a preserved part assumed, and the parts this gates (`DESIGN-PACKAGE-PASSTHROUGH.md`
75
- * §4's drop-if-structure-changed bucket) are exactly the ones a wrong guess here would corrupt.
76
- */
77
33
  hasStructuralChange(): boolean;
78
34
  markStructuralChange(): void;
79
35
  }
@@ -12,9 +12,8 @@ export interface WriteXLSXOptions extends IWorkbookIO.WriteOptions {
12
12
  *
13
13
  * @remarks
14
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.
15
+ * formats sharing this one handler. A single format listing both extensions could not express
16
+ * this, because the handler is never told which of its extensions is being written.
18
17
  *
19
18
  * It decides **both halves together**, so the declaration can never disagree with the payload:
20
19
  * the `xl/workbook.xml` content type, and whether a source package's `xl/vbaProject.bin` is
@@ -1,12 +1,3 @@
1
- /**
2
- * The style and colors parts a 2016 chart is written with when it has none of its own: Excel 16
3
- * refuses to open a workbook whose `cx:chartSpace` part lacks either, or has an empty one, and opens
4
- * one that has any complete pair (measured 2026-10-17, `probe-chart-write.ps1`: every 2016 type with
5
- * the waterfall's style opens clean). These are the parts Excel 16 wrote for a new waterfall
6
- * (`probe-chart-chartex.ps1`, `chart-chartex.xlsx`); its colors part is the same for every type.
7
- * Which style each type gets in Excel is in that file too; writing each type its own is Phase 4's
8
- * style tables.
9
- */
10
1
  export declare const CHART_STYLE_PART: {
11
2
  type: string;
12
3
  contentType: string;
@@ -1,4 +1,4 @@
1
- import { IWorkbook, IWorksheet } from '@sheetxl/sdk';
1
+ import { INamed, ITypes, IWorkbook } from '@sheetxl/sdk';
2
2
  /** What a cell's `<f>` turned out to be. */
3
3
  export type Unwrapped =
4
4
  /** Not a wrapper — use the text as-is. */
@@ -12,21 +12,12 @@ export type Unwrapped =
12
12
  }
13
13
  /**
14
14
  * A cell the original spilled INTO. It has no formula of its own and its cached value belongs to
15
- * the anchor's result, so BOTH must be dropped — leaving the value behind would block the
16
- * restored anchor from spilling and turn it into `#SPILL!`.
15
+ * the anchor's result, so it has to end up inside the anchor's extent — a plain value there would
16
+ * block the restored anchor from spilling and turn it into `#SPILL!`.
17
17
  */
18
18
  | {
19
19
  kind: 'spilled';
20
20
  };
21
- /** A wrapped cell found during parsing, resolved later by {@link applyDummyFunctionUnwrap}. */
22
- export interface DummyWrapRecord {
23
- /** Identity of the sheet's parse-time JSON; the reader maps it to the constructed sheet. */
24
- sheet: object;
25
- rowIndex: number;
26
- colIndex: number;
27
- /** The original formula text, or `null` when this cell is a spilled-into placeholder. */
28
- formula: string | null;
29
- }
30
21
  /**
31
22
  * Classifies a raw `<f>` text.
32
23
  *
@@ -40,19 +31,48 @@ export declare const unwrapDummyFunction: (text: string) => Unwrapped;
40
31
  * cannot be mistaken for a call, which is the whole reason this is not a regex.
41
32
  */
42
33
  export declare const extractFunctionNames: (text: string) => string[];
34
+ /** Whether a function called by a wrapped formula can run in the workbook being read. */
35
+ export type IsKnownFunction = (name: string) => boolean;
36
+ /**
37
+ * The functions a workbook will have, answered before it exists: the built-in declarations, the
38
+ * file's defined names, and the functions the caller is supplying to it.
39
+ */
40
+ export declare const createIsKnownFunction: (names: readonly INamed.JSON[] | undefined, providers: IWorkbook.ConstructorOptions["functions"]) => IsKnownFunction;
43
41
  /**
44
- * Restores the original formula for every wrapper whose functions this workbook actually has.
42
+ * Whether a wrapped formula calls a volatile function. The wrapper does not say so: to Excel it is
43
+ * a call to one unknown function.
44
+ */
45
+ export declare const callsVolatileFunction: (formula: string) => boolean;
46
+ /**
47
+ * Decides, one wrapper at a time as a sheet's cells are read, what each becomes.
48
+ *
49
+ * A wrapper whose functions are all known becomes the formula it wrapped, and a spilling one a
50
+ * dynamic array over the cached values of its placeholders. That is what the model loads for any
51
+ * stored array formula, so it opens with the file's values and is evaluated for the same reasons.
45
52
  *
46
- * Runs after the workbook is constructed, because that is the first moment the function registry
47
- * exists — and the registry is the whole question. Unwrapping a formula we cannot evaluate would
48
- * replace a correct cached value with `#NAME?`, which is worse than leaving the wrapper alone: the
49
- * wrapper at least still shows the right answer. So a wrapper naming anything unknown (a Sheets
50
- * function we do not implement, a UDF this session has not registered) is left exactly as it was.
53
+ * A wrapper naming anything unknown (a Sheets function we do not implement, a UDF nobody supplied)
54
+ * stays as it is, along with its placeholders: unwrapped, it would be `#NAME?` the first time it
55
+ * ran, and the wrapper keeps the right value on screen and in the next save.
51
56
  *
52
- * A spilled block is all-or-nothing. The placeholders are claimed by flood fill from the anchor —
53
- * spill blocks are contiguous, so a placeholder connected to a resolvable anchor belongs to it —
54
- * and are cleared BEFORE the anchor's formula is restored, since the restored formula needs those
55
- * cells free to spill into. Placeholders of an unresolved anchor keep their values.
57
+ * The cells arrive in reading order, so an anchor precedes its placeholders. Only the placeholder
58
+ * side needs looking up: a block is rectangular, so its first row is what runs right of the anchor,
59
+ * and each later row sits under the one above. A block's own column takes a placeholder ahead of a
60
+ * neighbor's row, because a scalar wrapper beside a spill is the usual reason the two ever touch.
56
61
  */
57
- export declare const applyDummyFunctionUnwrap: (workbook: IWorkbook, records: DummyWrapRecord[], sheetsByRef: Map<object, IWorksheet>) => void;
62
+ export declare class DummyFunctionRestorer {
63
+ private _isKnown;
64
+ private _restored;
65
+ /** The block last seen in each column. */
66
+ private _byColumn;
67
+ constructor(isKnown: IsKnownFunction);
68
+ /** Whether the wrapped formula at this cell is restored. A cell is asked about at most once. */
69
+ anchor(rowIndex: number, colIndex: number, formula: string): boolean;
70
+ /** Whether the placeholder at this cell belongs to a restored block. */
71
+ placeholder(rowIndex: number, colIndex: number): boolean;
72
+ /**
73
+ * Every restored block, whether it spilled or not. An unmarked formula is a legacy one to the
74
+ * load, and would have its `@`s put back; the text in a wrapper was never spelled that way.
75
+ */
76
+ getFormulaArray(): [ref: string, kind: ITypes.FormulaArrayKind][];
77
+ }
58
78
  //# sourceMappingURL=DummyFunctionUnwrap.d.ts.map
@@ -12,14 +12,6 @@ export declare class AutoFilterVisitor implements Visitor {
12
12
  processColorFilter(context: ExecutionContext, elem: Element): ICondition.JSON;
13
13
  processCustomFilter(context: ExecutionContext, elem: Element): ICondition.JSON | null;
14
14
  processCustomFilters(context: ExecutionContext, elem: Element): ICondition.JSON;
15
- /**
16
- * `dynamicFilter` is Excel's Average (`aboveAverage` / `belowAverage`) or a TimePeriod.
17
- *
18
- * @remarks
19
- * `val` and `maxVal` are Excel's cache of the last evaluation (the average; a period's start
20
- * and exclusive end), not an anchor and not a deviation count. Excel honors `type` alone and
21
- * rewrites them on save (`probe-filter-dynamic`), so they are dropped here.
22
- */
23
15
  processDynamicFilter(context: ExecutionContext, elem: Element): ICondition.JSON;
24
16
  processDateGroupItem(context: ExecutionContext, elem: Element): ICondition.DateGroupItem;
25
17
  processFilterItem(context: ExecutionContext, elem: Element): Scalar | undefined;
@@ -32,16 +32,6 @@ export declare class ExternalLinkVisitor implements Visitor {
32
32
  private _findAbsoluteUrlRelId;
33
33
  }
34
34
  export declare namespace ExternalLinkVisitor {
35
- /**
36
- * The `r:id`s the part's XML points at, handed to `XLSXReader` so it can say which of the part's
37
- * relationships is the book's own path and which is the 2021 `absoluteUrl` companion — then
38
- * stripped. **Not part of {@link IExternalBook.JSON}**: an rId is a name inside one package, and
39
- * a saved book gets fresh ones.
40
- *
41
- * @remarks
42
- * The relationship type cannot answer this on its own — both can be `externalLinkPath` (measured
43
- * on task 40234).
44
- */
45
35
  interface RelIds {
46
36
  __bookRelId?: string;
47
37
  __absoluteUrlRelId?: string;
@@ -11,15 +11,6 @@ import { Visitor, ExecutionContext } from '../dom';
11
11
  export interface FeaturePropertyBags {
12
12
  controls: (ICellControl.JSON | null)[];
13
13
  }
14
- /**
15
- * Reads the feature property bags into the controls their complements stand for.
16
- *
17
- * @remarks
18
- * The chain (measured 2026-10-27, `checkbox.xlsx`): the `XFComplements` bag's
19
- * `MappedFeaturePropertyBags` array lists `XFComplement` bags, by position among all bags; each
20
- * names an `XFControls` bag (`k="XFControls"`), which names the control bag (`k="CellControl"`),
21
- * whose type is the control (`Checkbox`).
22
- */
23
14
  export declare class FeaturePropertyBagVisitor implements Visitor {
24
15
  visit(context: ExecutionContext, elem: Element, jsonParent: any): FeaturePropertyBags;
25
16
  private _readBag;
@@ -1,17 +1,6 @@
1
1
  import { ITheme } from '@sheetxl/sdk';
2
2
  import { Visitor, ExecutionContext } from '../dom';
3
3
  import { ColorContainerVisitor } from './ColorContainerVisitor';
4
- /**
5
- * Parses the source theme's `<a:fmtScheme>` (fill/line/effect/background-fill style lists) into
6
- * typed `ITheme.JSON` fields (`fillStyleLst`/`lnStyleLst`/`effectStyleLst`/`bgFillStyleLst`) so
7
- * idx-referencing shape/chart styles (`<a:lnRef idx="N">`, `<a:fillRef>`, `<a:effectRef>`) keep
8
- * resolving against the same source definitions on save — see DESIGN-PACKAGE-PASSTHROUGH.md §11.2.
9
- *
10
- * Each list that is fully modeled is kept, so the theme draws with the file's own fills and
11
- * lines. If any list isn't (an effect outside the "common" set — see `IEffect` — or a
12
- * `scene3d`/`sp3d` on an effect style), the whole `<a:fmtScheme>` is also captured verbatim
13
- * (`ITheme.JSON.formatSchemeXml`) and `ThemeEmitter` replays that instead of writing the lists.
14
- */
15
4
  export declare class FmtSchemeVisitor extends ColorContainerVisitor implements Visitor {
16
5
  visit(context: ExecutionContext, elemParent: Element, jsonParent: ITheme.JSON): void;
17
6
  private parseFillList;
@@ -20,15 +20,6 @@ export declare class WorkbookVisitor extends SheetColorContainerVisitor {
20
20
  * `getRef`, which normalizes an empty visitor result to `null` and attaches `sources`).
21
21
  */
22
22
  processExternalReferences(context: ExecutionContext, elem: Element, jsonParent: IWorkbook.JSON): any;
23
- /**
24
- * `<pivotCaches><pivotCache cacheId="n" r:id="rIdN"/></pivotCaches>` — the workbook's pivot
25
- * caches, each carried whole: its definition part and, through that part's own relationships,
26
- * its records. See `PLAN-MODEL-HOMES.md` step 4.
27
- *
28
- * @remarks
29
- * The id is the join key: every pivot table names the cache it summarizes by `cacheId`, and the
30
- * writer puts the same id back so the two still meet.
31
- */
32
23
  processPivotCaches(context: ExecutionContext, elem: Element, jsonParent: IWorkbook.JSON): any;
33
24
  processBookViews(context: ExecutionContext, elem: Element, jsonParent: IWorkbook.JSON): any;
34
25
  processWorkbookView(context: ExecutionContext, elem: Element, jsonParent: IWorkbook.JSON): any;
@@ -43,20 +43,5 @@ export declare class RunCollector {
43
43
  */
44
44
  take(): IRichText.Run[] | null;
45
45
  }
46
- /**
47
- * The runs as a cell holds them: a run with an `<rPr>` gets the whole font Excel reads it as,
48
- * a run without one stays bare.
49
- *
50
- * @remarks
51
- * Measured (`probe-rich-partial.ps1`, 2026-10-18): Excel reads an `<rPr>` as absolute over the
52
- * workbook's DEFAULT font, not the cell's. `<rPr><i/></rPr>` over an Arial 12 bold cell renders
53
- * Calibri 11 italic, not bold; an empty `<rPr/>` (openpyxl) renders the default font; only a run
54
- * with no `<rPr>` inherits the cell font. So a run with an `<rPr>` is completed here from the
55
- * default font with every toggle off, then what the `<rPr>` states; the run then means the same
56
- * read as a delta over any cell font.
57
- *
58
- * @param defaultFont The workbook's Normal font (family, size, color); absent, Excel's
59
- * own default.
60
- */
61
46
  export declare function completeRuns(runs: readonly IRichText.Run[], defaultFont: IFontStyle.JSON | undefined): IRichText.Run[];
62
47
  //# sourceMappingURL=SharedStringsVisitor.d.ts.map
@@ -1,4 +1,4 @@
1
- import { Tuple, Scalar, IWorksheet } from '@sheetxl/sdk';
1
+ import { Scalar, Tuple, IWorksheet } from '@sheetxl/sdk';
2
2
  import { SaxParser } from '../sax';
3
3
  import { OnWarning } from '../Warning';
4
4
  /**
@@ -6,6 +6,8 @@ import { OnWarning } from '../Warning';
6
6
  * dialect (`XlsxFormulaDialect`), for condition formulas. Set before any sheet streams.
7
7
  */
8
8
  export declare const PARAM_FORMULA_DIALECT = "formulaDialect";
9
+ /** {@link IsKnownFunction}, set when wrapped formulas are to be restored. Read at the first wrapper. */
10
+ export declare const PARAM_IS_KNOWN_FUNCTION = "isKnownFunction";
9
11
  /**
10
12
  * The `paramMap` key under which the reader hands the worksheet visitor `workbookPr@date1904`, for
11
13
  * `t="d"` cells. Read per cell, not when the visitor is made: it is set once `workbook.xml` is read,
@@ -19,11 +19,6 @@ export interface WrittenWebImage {
19
19
  * indexes this list. Empty when the part is absent.
20
20
  */
21
21
  export declare const readWebImages: (ctx: RichValueReadContext) => WebImage[];
22
- /**
23
- * How a picture reached its cell, as a `_webimage`'s `CalcOrigin` says it: 1 for the result of an
24
- * `IMAGE` call and 4 for a reference to one (`=A3`), as Excel writes them (probe-image-fetch,
25
- * 2026-10-27). 2 for any other formula and 5 for a literal are [MS-XLSX]'s values as read, unprobed.
26
- */
27
22
  export declare const calcOriginOf: (formula: string | null) => number;
28
23
  /**
29
24
  * Excel's `_webimage` structure: a picture as a cell value (`IMAGE`), read as and written from an
@@ -1,23 +1,4 @@
1
1
  import { IColor, IFill, IStroke } from '@sheetxl/sdk';
2
- /**
3
- * A note box's fill and line: the VML of the note's `<v:shape>` and the model's
4
- * {@link IFill.JSON} / {@link IStroke.JSON}, both ways.
5
- *
6
- * @remarks
7
- * Probed with hidden COM (2026-10-20, `comments-probes/probe-note-format.ps1`). Excel writes the
8
- * fill as `fillcolor` on the shape with its transparency as `<v:fill opacity>`, and no fill as
9
- * `filled="f"` (the color left where it was). The line is `strokecolor`, `strokeweight` and
10
- * `stroked="f"` on the shape, with the dash and the compound on `<v:stroke dashstyle linestyle>`.
11
- * A color is a CSS color (`red`, `#cfc`), or a name and a palette index (`infoBackground [80]`);
12
- * Excel refuses a theme color here, so one is written as the color it resolves to.
13
- *
14
- * A named VML dash draws the same lengths as the DrawingML preset it is mapped to (`shortdash`
15
- * is `sysDash`, `3 1`), so a note draws the dash VML draws. Excel's own pairing through COM is
16
- * not by length and is not followed.
17
- *
18
- * Only a solid fill is modeled. A gradient, pattern or picture fill (`<v:fill type>`) is left in
19
- * the markup as it was read, and the box draws Excel's default fill.
20
- */
21
2
  /** A note box's fill and line, as the model states them. */
22
3
  export interface NoteShapeStyle {
23
4
  fill?: IFill.JSON;
@@ -45,25 +45,6 @@ export declare namespace VBAProject {
45
45
  codePage: number;
46
46
  modules: Module[];
47
47
  }
48
- /**
49
- * Extract all VBA modules, with their source, from a raw `xl/vbaProject.bin`.
50
- *
51
- * The `dir` stream is a flat sequence of `Id(2) Size(4) Data(Size)` records,
52
- * **with one exception**: `PROJECTVERSION` (0x0009) stores a fixed reserved value
53
- * `4` in the size slot but is followed by 6 bytes (VersionMajor + VersionMinor).
54
- * Treating its size as a skip length misaligns everything after it — which is why
55
- * a naive walk never finds the module records.
56
- *
57
- * @param vbaProjectBin The bytes of the `xl/vbaProject.bin` part.
58
- * @returns The parsed project, or `null` if the bytes are not a compound file.
59
- *
60
- * @remarks
61
- * Deliberately eager. A lazy variant existed briefly, deferring each module's stream until
62
- * someone read it; measured on the corpus it saved **7µs** — the cost is the compound-file walk
63
- * and the `dir` decompress, which happen either way, and the per-module streams are noise beside
64
- * them. What it cost was a module JSON whose properties existed before their values did, which
65
- * is not a trade worth making for microseconds.
66
- */
67
48
  const extract: (vbaProjectBin: Uint8Array | ArrayBuffer) => Project | null;
68
49
  /** A module's source, separated into the part VBA hides and the part it shows. */
69
50
  interface Source {
@@ -1,11 +1,3 @@
1
- /**
2
- * Minimal, dependency-free parsing for the two flat OPC manifest formats the writer needs to read
3
- * back from a retained source package: `[Content_Types].xml` and `*.rels`. Both are, per spec, a
4
- * single level of self-closing elements with only attributes — no text content, no nesting beyond
5
- * the root — so an attribute-order-independent regex parser is enough, and it keeps the writer from
6
- * needing a DOM parser (it otherwise only ever produces XML, never parses it). See
7
- * `DESIGN-PACKAGE-PASSTHROUGH.md` §6.
8
- */
9
1
  export declare function decodeXmlEntities(s: string): string;
10
2
  export interface SourceContentTypes {
11
3
  readonly defaults: readonly {