@sheetxl/io-xlsx 0.8.0-beta.1 → 0.8.0-beta.3

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 (88) hide show
  1. package/browser/cjs/BGFXHa9DqD7qfj7K.cjs +5 -0
  2. package/browser/cjs/C8oC1tPbhgR0Dqtx.cjs +2 -0
  3. package/browser/cjs/CIQ0CyhkW02G7UhX.cjs +1 -0
  4. package/browser/cjs/{D5Y4KQhKdukOkjvA.cjs → D3EWCPfCu-qMOIGd.cjs} +1 -2
  5. package/browser/cjs/{BAtEL-5TLyoaPFDP.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/{BkNXyG6NC-w5Xo92.mjs → 9kAH9485xCkOzN_I.mjs} +28 -13
  10. package/browser/esm/{Cok_fBIUCHDSrKw0.mjs → B8BqrWUHPa06PzmO.mjs} +446 -347
  11. package/browser/esm/{Dj7D2nVdAZ3TiUks.mjs → BdmxnPd0ptyqOCaM.mjs} +1595 -1124
  12. package/browser/esm/BzlhIt5zSG0Ts4xd.mjs +3324 -0
  13. package/browser/esm/CED9M7CASY6R5LBH.mjs +159 -0
  14. package/browser/esm/{4BWLu134ABlCQEtM.mjs → DNwAYvPHH1G27K-w.mjs} +1824 -1051
  15. package/browser/esm/{ijQzHH-bvDfUHIi1.mjs → DbSKfjIyE4a1YHoX.mjs} +1 -1
  16. package/browser/esm/{Dz1Dp8DDJvhd09RR.mjs → DtypWHI_cwfAvvyR.mjs} +1 -1
  17. package/browser/esm/PpS5wqbPAZ9D3W7c.mjs +67 -0
  18. package/browser/esm/{Ctqql4O-3xj2K8vv.mjs → aL7oQqItresvrEf2.mjs} +2 -2
  19. package/browser/esm/{CLWzJJyoSrykkVLX.mjs → h9ucGRwzGRA2N44D.mjs} +2 -2
  20. package/browser/esm/index.mjs +3 -3
  21. package/node/esm/{fOnuUjpPCAzmuIXN.mjs → A5sK8gK9ymQOyChG.mjs} +2 -2
  22. package/node/esm/CCD1vEduHhKax_d_.mjs +170 -0
  23. package/node/esm/{CF1R5ovFsRNu--Rw.mjs → CJGTDWKH_yrWAW8o.mjs} +1934 -1143
  24. package/node/esm/{CEAmv36xpTNgFwl_.mjs → CsTuNxyS02vBz0Tk.mjs} +49 -35
  25. package/node/esm/{Ctcl4jN52INWpKWC.mjs → DOXXVsfrZi_6L0V7.mjs} +607 -506
  26. package/node/esm/OkoETXoPSSH3gQxa.mjs +2959 -0
  27. package/node/esm/TERvDGVSsvCefEiX.mjs +3410 -0
  28. package/node/esm/index.mjs +40 -25
  29. package/node/esm/{CEV7nKotMpeRRnQC.mjs → mlCt7xhd97xcwrEr.mjs} +1 -1
  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/OpcXmlUtils.d.ts +2 -0
  63. package/types/src/writer/builder/PackageBuilder.d.ts +70 -22
  64. package/types/src/writer/builder/PartWriter.d.ts +5 -0
  65. package/types/src/writer/builder/RelationshipSet.d.ts +3 -0
  66. package/types/src/writer/builder/Types.d.ts +107 -38
  67. package/types/src/writer/builder/_Types.d.ts +17 -0
  68. package/types/src/writer/emitters/CommentsEmitter.d.ts +52 -0
  69. package/types/src/writer/emitters/EmbeddedPartEmitter.d.ts +60 -0
  70. package/types/src/writer/emitters/ExternalLinkEmitter.d.ts +19 -0
  71. package/types/src/writer/emitters/LegacyDrawingEmitter.d.ts +18 -0
  72. package/types/src/writer/emitters/PersonsEmitter.d.ts +17 -0
  73. package/types/src/writer/emitters/PivotTableEmitter.d.ts +45 -0
  74. package/types/src/writer/emitters/ThreadedCommentsEmitter.d.ts +21 -0
  75. package/types/src/writer/emitters/WorkbookEmitter.d.ts +16 -3
  76. package/types/src/writer/utils/DrawMLUtils.d.ts +16 -1
  77. package/types/src/writer/utils/HiddenFormulaXfs.d.ts +28 -0
  78. package/browser/cjs/Bg0e53JZa8vhmm5a.cjs +0 -1
  79. package/browser/cjs/CK5FFUvet6FnIYO_.cjs +0 -5
  80. package/browser/cjs/DV6LeTEiiFUrZoxj.cjs +0 -1
  81. package/browser/cjs/DWkuoJSgvcXJTdN1.cjs +0 -1
  82. package/browser/cjs/Db8YjGM6TG34c8aT.cjs +0 -1
  83. package/browser/esm/BzQ_lPzc8C4OTIGZ.mjs +0 -99
  84. package/browser/esm/CJknI8BYGSZr-4zS.mjs +0 -52
  85. package/browser/esm/D-m_kQLaewdwuXaF.mjs +0 -2685
  86. package/node/esm/CvnRSooxEQdlJgMn.mjs +0 -2766
  87. package/node/esm/DQd0vxzTaPt2qSL-.mjs +0 -108
  88. package/node/esm/ssSlRCbCqxvZ9IX8.mjs +0 -2481
@@ -12,12 +12,33 @@
12
12
  * compiled "performance cache" we skip) and decoded with the project code page.
13
13
  */
14
14
  export declare namespace VBAProject {
15
+ /**
16
+ * What kind of module this is (MS-OVBA `MODULETYPE`).
17
+ *
18
+ * @remarks
19
+ * The distinction is semantic, not cosmetic: only `procedural` modules contribute
20
+ * functions to the worksheet formula namespace. A UDF declared in a `document`
21
+ * module is unreachable from a formula.
22
+ *
23
+ * `document` is the spec's `0x0021`/`0x0022` split, so it is broader than its name:
24
+ * `0x0022` covers document modules **and** class and designer (UserForm) modules.
25
+ * Which object a `document` module belongs to — a sheet, the workbook, or nothing
26
+ * addressable — is answered by matching {@link Module.name} against code names, not
27
+ * by this field.
28
+ */
29
+ type ModuleType = 'procedural' | 'document';
15
30
  /** A single extracted VBA module. */
16
31
  interface Module {
17
32
  /** Module name as shown in the VBE project tree (e.g. `Module1`, `ThisWorkbook`). */
18
33
  name: string;
19
34
  /** Full source, including the leading `Attribute VB_*` lines Excel keeps hidden. */
20
35
  code: string;
36
+ /**
37
+ * Standard (`procedural`) module, or a document module bound to the workbook or
38
+ * a sheet. For a document module {@link Module.name} is the code name of the
39
+ * object it belongs to.
40
+ */
41
+ type: ModuleType;
21
42
  }
22
43
  interface Project {
23
44
  /** Code page declared by the project (e.g. 1252). */
@@ -25,7 +46,7 @@ export declare namespace VBAProject {
25
46
  modules: Module[];
26
47
  }
27
48
  /**
28
- * Extract all VBA modules from a raw `xl/vbaProject.bin`.
49
+ * Extract all VBA modules, with their source, from a raw `xl/vbaProject.bin`.
29
50
  *
30
51
  * The `dir` stream is a flat sequence of `Id(2) Size(4) Data(Size)` records,
31
52
  * **with one exception**: `PROJECTVERSION` (0x0009) stores a fixed reserved value
@@ -35,12 +56,39 @@ export declare namespace VBAProject {
35
56
  *
36
57
  * @param vbaProjectBin The bytes of the `xl/vbaProject.bin` part.
37
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.
38
66
  */
39
67
  const extract: (vbaProjectBin: Uint8Array | ArrayBuffer) => Project | null;
68
+ /** A module's source, separated into the part VBA hides and the part it shows. */
69
+ interface Source {
70
+ /**
71
+ * The leading `Attribute VB_*` block. Bookkeeping VBA hides from the editor, and not
72
+ * derivable from anything else — `VB_Base` names an interface GUID, `VB_PredeclaredId` and
73
+ * `VB_Exposed` are per-module settings — so it is kept rather than reconstructed.
74
+ */
75
+ header: string;
76
+ /** What the VBA editor displays. Empty for a document module nobody has written in. */
77
+ body: string;
78
+ }
40
79
  /**
41
- * Strip the leading hidden `Attribute VB_*` lines from a module's source so the
42
- * result matches what the VBA editor displays. Procedure-level `Attribute` lines
43
- * (indented, inside a `Sub`/`Function`) are left untouched.
80
+ * Split a module's source into its hidden `Attribute VB_*` header and the source proper.
81
+ *
82
+ * @remarks
83
+ * Only the leading module-level block is header. Procedure-level `Attribute` lines (indented,
84
+ * inside a `Sub`/`Function`) belong to the body — VBA hides those in the editor too, but they
85
+ * sit inside code and cannot be lifted out of it.
86
+ */
87
+ const splitAttributes: (code: string) => Source;
88
+ /**
89
+ * The source without its hidden `Attribute VB_*` header.
90
+ *
91
+ * @see {@link splitAttributes} to keep the header as well.
44
92
  */
45
93
  const stripAttributes: (code: string) => string;
46
94
  }
@@ -12,6 +12,19 @@ export declare class ContentTypes {
12
12
  constructor();
13
13
  addDefault(ext: string, contentType: string): void;
14
14
  addOverride(partName: string, contentType: string): void;
15
+ /**
16
+ * Change the content type already recorded for `partName`, keeping its position in the document.
17
+ *
18
+ * @remarks
19
+ * {@link addOverride} is first-wins, which is right for the emitters that race to declare a part.
20
+ * This is the deliberate exception: a *variant* of a part an emitter already claimed, decided
21
+ * only once the whole package is known. The workbook part is the case that needs it — whether it
22
+ * is `…spreadsheetml.sheet.main+xml` or `…ms-excel.sheet.macroEnabled.main+xml` depends on
23
+ * whether a VBA project ended up in the package, which no emitter can know while emitting.
24
+ *
25
+ * A no-op when `partName` has no override yet: this replaces a declaration, it never invents one.
26
+ */
27
+ replaceOverride(partName: string, contentType: string): void;
15
28
  toXmlBytes(): Uint8Array;
16
29
  }
17
30
  export declare const NS_CT = "http://schemas.openxmlformats.org/package/2006/content-types";
@@ -13,12 +13,12 @@ export declare abstract class Emitter<T = any> implements IEmitter<T> {
13
13
  });
14
14
  /** @inheritdoc IEmitter.emit */
15
15
  abstract emit(instance: T, ctx: EmitContext): Promise<void> | void;
16
- /** @inheritdoc IEmitter.kind */
17
- get kind(): string;
18
- /** @inheritdoc IEmitter.contentType */
19
- get contentType(): string;
20
- /** @inheritdoc IEmitter.relTypeUri */
21
- get relTypeUri(): string;
16
+ /** @inheritdoc IEmitter.getKind */
17
+ getKind(): string;
18
+ /** @inheritdoc IEmitter.getContentType */
19
+ getContentType(_instance?: T): string;
20
+ /** @inheritdoc IEmitter.getRelTypeUri */
21
+ getRelTypeUri(_instance?: T): string;
22
22
  /** @inheritdoc IEmitter.getPath */
23
23
  getPath(instance: T): string;
24
24
  }
@@ -17,6 +17,8 @@ export interface SourceContentTypes {
17
17
  }
18
18
  export declare function parseContentTypesXml(bytes: Uint8Array): SourceContentTypes;
19
19
  export interface SourceRelationship {
20
+ /** The source's own `rId`, meaningful only to the part that declared it. */
21
+ readonly id: string;
20
22
  readonly type: string;
21
23
  /** Verbatim from the source XML — relative to the referencing part, exactly as OPC requires. */
22
24
  readonly target: string;
@@ -63,9 +63,30 @@ export declare class PackageBuilder<Out> {
63
63
  private _registry;
64
64
  private _options;
65
65
  private _sourcePackage;
66
+ /** See {@link PackageBuilderOptions.macroEnabled}. */
67
+ private _macroEnabled;
66
68
  private _explicitRelTargets;
67
69
  private _mapState;
68
70
  constructor(zip: IZipBackend<Out>, registry: EmitterRegistry, options?: PackageBuilderOptions);
71
+ /**
72
+ * Whether a source part named `name` will be in this package once {@link _passthroughSourceParts}
73
+ * has run — the drop rules of `DESIGN-PACKAGE-PASSTHROUGH.md` §4, as one predicate. `false` when
74
+ * there is no source package or it has no such part.
75
+ *
76
+ * @remarks
77
+ * Does not consider whether an emitter claimed the *path* — that part is then in the package, but
78
+ * as the emitter's, not the source's. It does consider whether the reader took the part onto the
79
+ * model ({@link ISourcePackage.isAbsorbed}), which is a different question: the model writes that
80
+ * part wherever its own numbering puts it, which need not be where the source had it.
81
+ */
82
+ private _isSourcePartCarried;
83
+ /**
84
+ * Hold the source's own relationship ids back in `partPath`'s set, before the emitter rewriting
85
+ * that part allocates anything — see {@link IRelationshipSet.reserve}. The emitter's edges then
86
+ * go above them, and a source edge {@link _mergeSourceRelsInto} carries back in afterwards keeps
87
+ * its name, which is what a captured source fragment replayed inside the part still cites.
88
+ */
89
+ private _reserveSourceRelIds;
69
90
  /**
70
91
  * Wait for all scheduled parts to be emitted.
71
92
  */
@@ -88,13 +109,51 @@ export declare class PackageBuilder<Out> {
88
109
  */
89
110
  private _passthroughSourceParts;
90
111
  /**
91
- * Seed `sourcePart`'s {@link IRelationshipSet} with the source's edges: drop one whose target an
92
- * emitter already claimed (that emitter made its own, correct edge already — keeping both would
93
- * duplicate it), drop one whose target did not survive at all (§5), keep the rest verbatim. Always
94
- * allocates a fresh rId (never the source's) — the edge is what matters, not its name, and reusing
95
- * the source's `rIdN` strings would collide with whatever an emitter already allocated in this same
96
- * set. Targets are carried forward as-is (still relative to the same referencing part, at the same
97
- * OPC path) — nothing to recompute.
112
+ * Declare the workbook part's macro-enabled **variant** of `CT_Workbook` when the package being
113
+ * built is one — the difference between `…spreadsheetml.sheet.main+xml` and
114
+ * `…ms-excel.sheet.macroEnabled.main+xml`.
115
+ *
116
+ * @remarks
117
+ * `xl/workbook.xml` is emitter-claimed, and its emitter declares the plain variant unconditionally
118
+ * because macro-enabledness is not a property of the workbook — it is a property of the format
119
+ * being written to, which no emitter can see. Without this a macro workbook would be saved
120
+ * carrying a VBA project it no longer admits to: the payload preserved and every statement about
121
+ * it wrong.
122
+ *
123
+ * The decision is {@link PackageBuilderOptions.macroEnabled}, i.e. purely the resolved write
124
+ * format, and the **same flag also decides whether the project part is carried**
125
+ * ({@link _passthroughSourceParts}). Deriving both from one input is what makes it impossible for
126
+ * the declaration and the payload to disagree — the earlier attempt inferred the variant from the
127
+ * source package instead, which got an `.xlsm`-to-`.xlsx` export wrong in both halves at once.
128
+ *
129
+ * Independent of whether a project is actually present: a macro-enabled workbook containing no
130
+ * VBA at all is a legal thing for Excel to produce, and demoting it would silently change the
131
+ * file type the user asked for.
132
+ *
133
+ * Scoped to the workbook part on purpose. A blanket "source Override wins for claimed parts"
134
+ * would let a stale declaration through on anything.
135
+ */
136
+ private _applyWorkbookContentTypeVariant;
137
+ /**
138
+ * Seed `sourcePart`'s {@link IRelationshipSet} with the source's edges, each under the source's
139
+ * own id. Targets are carried forward as-is (still relative to the same referencing part, at the
140
+ * same OPC path) — nothing to recompute.
141
+ *
142
+ * @remarks
143
+ * Which edges come back depends on who wrote the part (`DESIGN-PACKAGE-PASSTHROUGH.md` §6):
144
+ *
145
+ * - A **preserved** part is the source's bytes, so its XML still cites the ids the source's
146
+ * `.rels` defined; every edge whose target is still in the package comes back with that id.
147
+ * Nothing else ever wrote into this set, so the ids are free.
148
+ * - A **rewritten** part (the root, or one an emitter claimed) had its emitter recreate the edges
149
+ * it cites, so only what the emitter did not recreate is added: not an edge whose target an
150
+ * emitter claimed (its own, correct edge exists already — keeping both would duplicate it), not
151
+ * one added by name through `addRelationship`. The set had the source's ids reserved before
152
+ * the emitter allocated ({@link _reserveSourceRelIds}), so these too keep their names —
153
+ * unless an emitter took the id as a hint for a different target, in which case it is fresh.
154
+ *
155
+ * An edge whose target did not survive at all is dropped either way (§5). A `TargetMode="External"`
156
+ * or `#`-fragment target is not a part and is never resolved as one.
98
157
  */
99
158
  private _mergeSourceRelsInto;
100
159
  /**
@@ -104,8 +163,8 @@ export declare class PackageBuilder<Out> {
104
163
  * @param instance The instance of the part to add.
105
164
  * @returns The path of the added root part.
106
165
  */
107
- addPart<T = any>(kind: string, instance: T, pathTemplate?: string): PackagePart;
108
- protected _addPartInternal<T = any>(currentPartPath: string, kind: string, instance: T, pathTemplate?: string): PackagePart;
166
+ addPart<T = any>(kind: string, instance: T, pathTemplate?: string, idHint?: string): PackagePart;
167
+ protected _addPartInternal<T = any>(currentPartPath: string, kind: string, instance: T, pathTemplate?: string, idHint?: string): PackagePart;
109
168
  /**
110
169
  * Add a binary to the package.
111
170
  *
@@ -119,19 +178,8 @@ export declare class PackageBuilder<Out> {
119
178
  * @remarks
120
179
  * Override is only used if the path is not a template
121
180
  */
122
- addBinary(bytes: Uint8Array, contentType: string, relTypeUri: string, pathTemplate: string, override?: boolean): PackagePart;
123
- protected _addBinaryInternal(currentPartPath: string, bytes: Uint8Array, contentType: string, relTypeUri: string, pathTemplate: string, override?: boolean): PackagePart;
124
- /**
125
- * Implements {@link EmitContext.forkPreservedPart}.
126
- *
127
- * @remarks
128
- * The collision domain for the new path includes every name the source package could still emit
129
- * via passthrough, not just what's already been written — `_passthroughSourceParts` (which is what
130
- * actually registers the *original* target's own path into {@link _writtenPaths}) only runs after
131
- * `waitEmit()` completes, so at fork time the source's own numbering (`chart2.xml` already existing
132
- * as an unrelated real chart, say) isn't visible there yet.
133
- */
134
- protected _forkPreservedPart(currentPartPath: string, sourcePartPath: string, contentType: string, relTypeUri: string, pathTemplate: string): PackagePart | null;
181
+ addBinary(bytes: Uint8Array, contentType: string, relTypeUri: string, pathTemplate: string, override?: boolean, idHint?: string): PackagePart;
182
+ protected _addBinaryInternal(currentPartPath: string, bytes: Uint8Array, contentType: string, relTypeUri: string, pathTemplate: string, override?: boolean, idHint?: string): PackagePart;
135
183
  protected _waitForDescendants(parentPath: string): Promise<void>;
136
184
  protected _processPart(node: Scheduled): Promise<void>;
137
185
  }
@@ -12,6 +12,11 @@ export declare class PartWriter<Out = any> implements IPartWriter<Out> {
12
12
  addContentType(path: string, contentType: string): void;
13
13
  /** @inheritdoc IPartWriter.addDefaultType */
14
14
  addDefaultType(extension: string, contentType: string): void;
15
+ /**
16
+ * Change the content type already declared for `path`. See {@link ContentTypes.replaceOverride} —
17
+ * this exists for a part whose *variant* is only decidable once the whole package is known.
18
+ */
19
+ replaceContentType(path: string, contentType: string): void;
15
20
  /** @inheritdoc IPartWriter.addPart */
16
21
  addPart(path: string, body: PartBody, contentType: string, options?: ZipAddOptions): void;
17
22
  /** @inheritdoc IPartWriter.rels */
@@ -3,6 +3,7 @@ export declare class RelationshipSet implements IRelationshipSet {
3
3
  readonly sourcePart: string;
4
4
  private rels;
5
5
  private usedIds;
6
+ private reservedIds;
6
7
  private nextId;
7
8
  constructor(sourcePart: string);
8
9
  /** @inheritdoc IRelationshipSet.add */
@@ -10,6 +11,8 @@ export declare class RelationshipSet implements IRelationshipSet {
10
11
  external?: boolean;
11
12
  idHint?: string;
12
13
  }): string;
14
+ /** @inheritdoc IRelationshipSet.reserve */
15
+ reserve(ids: Iterable<string>): void;
13
16
  /** @inheritdoc IRelationshipSet.list */
14
17
  list(): readonly IRelationship[];
15
18
  toXmlBytes(): Uint8Array;
@@ -129,8 +129,12 @@ export interface EmitContext {
129
129
  * "worksheets/sheet2.xml", etc.
130
130
  * This can also be used for folder names such as
131
131
  * "charts/chart{n}/chart1.xml".
132
+ *
133
+ * @param idHint A preferred relationship id, for a caller whose content already cites one. Honored
134
+ * only if free in this part's set, so read the returned {@link PackagePart.relId} rather than
135
+ * assuming it.
132
136
  */
133
- addPart<T = any>(kind: string, instance: T, pathTemplate?: string): PackagePart;
137
+ addPart<T = any>(kind: string, instance: T, pathTemplate?: string, idHint?: string): PackagePart;
134
138
  /**
135
139
  * Adds a binary part at a path.
136
140
  *
@@ -138,48 +142,45 @@ export interface EmitContext {
138
142
  * @param contentType The content type for the extension.
139
143
  * @param relTypeUri The relationship type URI.
140
144
  * @param pathTemplate This is a relative path from the package root
145
+ * @param override Whether an existing part at the resolved path is the same part, rather than a
146
+ * collision to number around.
147
+ * @param idHint A preferred relationship id, for a caller whose content already cites one (a
148
+ * replayed fragment). Honored only if free in this part's set, so the caller has to check the
149
+ * returned {@link PackagePart.relId} rather than assume it.
141
150
  */
142
- addBinary(bytes: Uint8Array, contentType: string, relTypeUri: string, pathTemplate: string, override?: boolean): PackagePart;
151
+ addBinary(bytes: Uint8Array, contentType: string, relTypeUri: string, pathTemplate: string, override?: boolean, idHint?: string): PackagePart;
143
152
  /**
144
153
  * Adds an external relationship to the current part.
145
154
  *
146
155
  * @param relTypeUri The relationship type URI.
147
156
  * @param targetUrl The target URL.
157
+ * @param idHint A preferred relationship id, for a caller whose content already cites one (a
158
+ * replayed part's `<worksheetSource r:id>`). Honored only if free in this part's set, so read the
159
+ * returned {@link PackagePart.relId} rather than assuming it.
148
160
  *
149
161
  * @returns The rId of the added relationship.
150
162
  */
151
- addExternal(relTypeUri: string, targetUrl: string): PackagePart;
163
+ addExternal(relTypeUri: string, targetUrl: string, idHint?: string): PackagePart;
152
164
  /**
153
- * Adds a relationship from the current part to an existing part in the source package that no
154
- * emitter claims — the bytes are supplied later by the generic passthrough mechanism, not by the
155
- * caller. Unlike `addPart`/`addBinary`, this references content rather than creating it.
165
+ * Adds a relationship from the current part to a part that is already going to be in this
166
+ * package, rather than creating one: either a part another emitter wrote — one that is shared,
167
+ * written once by whoever owns it and referenced from each part that uses it (a pivot cache,
168
+ * written by the workbook, from every pivot table on it) — or a part the source package carries
169
+ * through untouched because nothing modeled it (a `<ddeLink>` external link).
156
170
  *
157
171
  * @param relTypeUri The relationship type URI.
158
172
  * @param targetPartPath The target's absolute path (relative to the package root, no leading `/`).
159
- * @param idHint A preferred id (e.g. the source's own original rId) — used only if it does not
160
- * collide with an id already assigned in this part's relationship set; falls back silently to an
161
- * auto-generated id otherwise, so a caller that needs the id to line up with something it already
162
- * wrote (e.g. a captured raw fragment referencing this target) must use the returned value, not
163
- * assume the hint was honored.
164
- * @returns The id actually assigned.
165
- */
166
- addPreservedRelationship(relTypeUri: string, targetPartPath: string, idHint?: string): string;
167
- /**
168
- * Mints an independent copy of a source-package part's bytes under a fresh path, and adds a
169
- * relationship from the current part to that copy. For when a source part must never be shared by
170
- * more than one reference — unlike `addPreservedRelationship`, which links to the one shared
171
- * target — e.g. a chart part, which a same-source movable copy would otherwise leave two anchors
172
- * both pointing at (see `DESIGN-PACKAGE-PASSTHROUGH.md` §11.2). The copy's own relationships (if
173
- * it has a `.rels` part in the source) are carried forward verbatim to the new path, so nested
174
- * references inside the copied bytes (e.g. a chart's colors/style/embedded data) keep resolving.
175
- *
176
- * @param sourcePartPath The absolute path of the source part to copy (no leading `/`).
177
- * @param contentType The content type for the copy.
178
- * @param relTypeUri The relationship type URI.
179
- * @param pathTemplate The path template for the copy — same `{n}` rules as `addBinary`.
180
- * @returns The new part, or `null` if there is no source package or the source part is missing.
181
- */
182
- forkPreservedPart(sourcePartPath: string, contentType: string, relTypeUri: string, pathTemplate: string): PackagePart | null;
173
+ * @param idHint A preferred id (e.g. the source's own original rId), honored only if free in this
174
+ * part's set; it falls back silently to an auto-generated id otherwise, so a caller that needs the
175
+ * id to line up with something it already wrote (a replayed fragment citing this target) must use
176
+ * the returned value rather than assume the hint was honored.
177
+ * @returns The id assigned, or `null` if the target will not be in the package — no emitter
178
+ * claimed the path and no source part survives at it (there is no source package, it has no such
179
+ * part, the model absorbed it, or it is in a drop bucket for this save; see
180
+ * `DESIGN-PACKAGE-PASSTHROUGH.md` §4). Nothing was added in that case: the caller must not write
181
+ * the element that would have cited it.
182
+ */
183
+ addRelationship(relTypeUri: string, targetPartPath: string, idHint?: string): string | null;
183
184
  /**
184
185
  * Waits for all dependants to be emitted.
185
186
  */
@@ -194,27 +195,70 @@ export interface EmitContext {
194
195
  getSharedStates(): Map<string, any>;
195
196
  /**
196
197
  * Warns that something is not quite right.
198
+ *
199
+ * @param message What was found.
200
+ * @param context Locates the finding. Defaults to the path of the part being emitted.
201
+ * @param onceKey Reports only the first warning carrying this key, for one write. A finding whose
202
+ * message names the specific thing it found (a formula, a length) is one per instance without a
203
+ * key and one per file with one. Keys are stable dotted identifiers (`xlsx.dv.listUnion`), never
204
+ * derived from the message text.
205
+ */
206
+ warn(message: string, context?: any, onceKey?: string): void;
207
+ /**
208
+ * Reports a fault in the writer itself — an inconsistency the user did not cause and cannot act on
209
+ * (a relationship id that could not be kept, an entry the model should never hold).
210
+ *
211
+ * @remarks
212
+ * Goes to the console, not to {@link warn}: a warning tells the user that something in their
213
+ * workbook was not written, and this is not that.
214
+ *
215
+ * @param message What was found.
216
+ * @param context Locates the finding. Defaults to the path of the part being emitted.
197
217
  */
198
- warn(message: string, context?: any): void;
218
+ log(message: string, context?: any): void;
199
219
  }
220
+ /**
221
+ * Shared-states key: the workbook's resources by the id the writer's JSON references them by.
222
+ *
223
+ * @remarks
224
+ * The JSON the emitters write from is built with a resource writer rather than embedding, and that
225
+ * writer fills this map as it is handed each resource. It is complete before any sheet part emits,
226
+ * so an emitter holding a `resId` from that JSON looks it up here to get back to the model's
227
+ * resource. Declared here rather than on the emitter that fills it because the emitters that read
228
+ * it sit below that one in the import graph.
229
+ *
230
+ * @see {@link EmitContext.getSharedStates}
231
+ */
232
+ export declare const SHARED_STATE_RESOURCES_BY_ID = "resourcesById";
200
233
  /**
201
234
  * A part emitter knows how to write a specific part type to XML (or binary).
202
235
  */
203
236
  export interface IEmitter<T = any> {
204
237
  /**
205
- * The type/kind of this part emitter
238
+ * The type/kind of this part emitter.
206
239
  */
207
- readonly kind: string;
240
+ getKind(): string;
208
241
  /**
209
- * Used to populate the [Content_Types].xml for THIS kind
242
+ * The content type to declare in `[Content_Types].xml` for this part.
243
+ *
244
+ * @remarks
245
+ * Takes the instance because an emitter's kind is not always one type of document part: one that
246
+ * replays a subtree carried on the model writes whatever each part in it says it is. Most emitters
247
+ * answer with the single type they were constructed with and ignore the argument.
248
+ *
249
+ * With no instance, the answer is what this emitter always writes, or `''` for one that only ever
250
+ * knows per instance.
210
251
  */
211
- readonly contentType: string;
252
+ getContentType(instance?: T): string;
212
253
  /**
213
- * Used to populate the (_rels/.rels) for THIS kind
254
+ * The relationship type to write into the referencing part's `.rels`.
255
+ *
214
256
  * @remarks
215
- * If not specified, this part will not be listed in the .rels
257
+ * Takes the instance for the same reason as {@link IEmitter.getContentType}, and answers the same
258
+ * way with none. An empty result means no relationship is created, and the part will not be listed
259
+ * in any `.rels`.
216
260
  */
217
- readonly relTypeUri: string;
261
+ getRelTypeUri(instance?: T): string;
218
262
  /**
219
263
  * The function that emits this part
220
264
  */
@@ -248,6 +292,18 @@ export interface PackageBuilderOptions {
248
292
  * instead of being dropped. See `DESIGN-PACKAGE-PASSTHROUGH.md`.
249
293
  */
250
294
  sourcePackage?: ISourcePackage | null;
295
+ /**
296
+ * Whether the package being built is macro-enabled (`.xlsm`) rather than plain (`.xlsx`).
297
+ *
298
+ * @defaultValue false
299
+ *
300
+ * @remarks
301
+ * Set from the resolved write format, and it governs the **declaration and the payload
302
+ * together** so the two can never disagree: the `xl/workbook.xml` content-type variant, and
303
+ * whether a retained `xl/vbaProject.bin` is carried through. Writing to `.xlsx` therefore drops
304
+ * a source's VBA project, matching Excel's own *Save As*.
305
+ */
306
+ macroEnabled?: boolean;
251
307
  /**
252
308
  * Callback invoked when a part is emitted.
253
309
  *
@@ -266,6 +322,14 @@ export interface PackageBuilderOptions {
266
322
  * @param error The error that occurred.
267
323
  */
268
324
  onPartError?: (kind: string, path: string, error: any) => void | Promise<void>;
325
+ /**
326
+ * Receives every {@link BuildContext.warn} an emitter raises, in emit order and undeduplicated.
327
+ *
328
+ * @remarks
329
+ * Without one, warnings go to the console. The writer that owns the build collects them here and
330
+ * decides how to report them (see `writeXLSX`).
331
+ */
332
+ onWarning?: (message: string, context: any, onceKey?: string) => void;
269
333
  }
270
334
  /** A part's still-compressed bytes — structurally matches `../SourcePackage.SourcePackageRawPart`. */
271
335
  export interface ISourcePackageRawPart {
@@ -290,6 +354,11 @@ export interface ISourcePackage {
290
354
  getNames(): string[];
291
355
  has(name: string): boolean;
292
356
  getPart(name: string): ISourcePackagePart | null;
357
+ /**
358
+ * See `../SourcePackage.SourcePackage.isAbsorbed` — whether the reader took this part onto the
359
+ * model, so an emitter writes it and the source's copy is surplus.
360
+ */
361
+ isAbsorbed(name: string): boolean;
293
362
  /** See `../SourcePackage.SourcePackage.hasStructuralChange` — gates §4's drop-if-changed bucket. */
294
363
  hasStructuralChange(): boolean;
295
364
  }
@@ -42,6 +42,16 @@ export interface IPartWriter<Out = any> {
42
42
  * @param contentType - OPC content type for the extension.
43
43
  */
44
44
  addDefaultType(extension: string, contentType: string): void;
45
+ /**
46
+ * Replace the content type already declared for `path`, keeping its position in the manifest.
47
+ *
48
+ * @remarks
49
+ * {@link addContentType} is first-wins, which is what the emitters racing to declare a part
50
+ * want. This is the exception, for a part whose *variant* is only decidable once the whole
51
+ * package is known — see `PackageBuilder._carryWorkbookContentTypeVariant`. A no-op when `path`
52
+ * has no content type yet: it replaces a declaration, never invents one.
53
+ */
54
+ replaceContentType(path: string, contentType: string): void;
45
55
  /**
46
56
  * Get the relationship set for `sourcePart`.
47
57
  *
@@ -94,6 +104,13 @@ export interface IRelationshipSet {
94
104
  external?: boolean;
95
105
  idHint?: string;
96
106
  }): string;
107
+ /**
108
+ * Hold `ids` back from auto-assignment, so that an edge added later with one of them as its
109
+ * `idHint` gets it. For a part rewritten over a source part: the source's own ids are reserved
110
+ * before its emitter allocates anything, its edges go above them, and a source edge merged back in
111
+ * afterwards keeps the name any verbatim fragment inside the part still cites.
112
+ */
113
+ reserve(ids: Iterable<string>): void;
97
114
  /**
98
115
  * List all relationships in this set.
99
116
  */
@@ -0,0 +1,52 @@
1
+ import { IComment, ISheet } from '@sheetxl/sdk';
2
+ import { Emitter, EmitContext, IXmlWriter } from '../builder';
3
+ export declare const REL_TYPE_COMMENTS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
4
+ export declare const REL_TYPE_THREADED_COMMENTS = "http://schemas.microsoft.com/office/2017/10/relationships/threadedComment";
5
+ /**
6
+ * A comment as the emitters take it: the model and the cell it is on, resolved once by the
7
+ * worksheet emitter for both parts.
8
+ */
9
+ export interface CommentHandle {
10
+ comment: IComment;
11
+ /** The cell address, `B307`. */
12
+ ref: string;
13
+ /** The 0-based cell. */
14
+ row: number;
15
+ col: number;
16
+ }
17
+ /** What the worksheet emitter schedules: the sheet's comments, roots only, in reading order. */
18
+ export interface CommentsPartHandle {
19
+ sheet: ISheet;
20
+ comments: CommentHandle[];
21
+ }
22
+ /**
23
+ * Writes `xl/comments{n}.xml`: every comment on the sheet as a legacy `<comment>`.
24
+ *
25
+ * @remarks
26
+ * A note writes its own text, runs and all. A threaded comment writes the shadow Excel writes
27
+ * beside every thread — an author of `tc={id}` and the boilerplate an older Excel shows —
28
+ * which a current Excel pairs with the thread by `ref`. Authors are the part's `<authors>`
29
+ * list, one entry per distinct display name (and per thread for the shadows).
30
+ */
31
+ export declare class CommentsEmitter extends Emitter<CommentsPartHandle> {
32
+ constructor();
33
+ /** @inheritdoc IEmitter.emit */
34
+ emit(handle: CommentsPartHandle, ctx: EmitContext): Promise<void>;
35
+ }
36
+ /**
37
+ * The text a pre-2018 Excel shows for a thread it cannot read, as Excel itself writes it.
38
+ */
39
+ export declare function shadowText(comment: IComment): string;
40
+ /**
41
+ * `<r><rPr/><t>` per run, or a single `<t>` for plain text.
42
+ */
43
+ export declare function writeRichText(xml: IXmlWriter, content: IComment.Content): void;
44
+ /**
45
+ * The cell address of a comment, or `null` when its cell is gone.
46
+ */
47
+ export declare function commentRef(comment: IComment): {
48
+ ref: string;
49
+ row: number;
50
+ col: number;
51
+ } | null;
52
+ //# sourceMappingURL=CommentsEmitter.d.ts.map
@@ -0,0 +1,60 @@
1
+ import { IEmbeddedPart } from '@sheetxl/sdk';
2
+ import { Emitter, EmitContext, PackagePart } from '../builder';
3
+ /**
4
+ * Writes a part carried in the writer's JSON back into the package, and every part it references.
5
+ *
6
+ * @remarks
7
+ * The counterpart of `readEmbeddedPart` in the reader, and the same argument in reverse: a chart
8
+ * names its style, its colors, the shapes drawn over it and sometimes an embedded workbook by
9
+ * relationship id, so all of them come back or the file does not open. Each part says what it is
10
+ * (`type`, `contentType`), which is why one emitter can write all of them — see
11
+ * {@link IEmitter.getContentType}.
12
+ *
13
+ * Names are the source's, renumbered where they collide, and every part is written beside the one
14
+ * that references it. Neither is required by OPC — a part is found through its relationship, never
15
+ * by its name — but keeping `style1.xml` called that makes the output readable, and keeping a
16
+ * chart's shapes under `xl/charts/` is what retires the hazard of a sheet's `drawing{n}` landing on
17
+ * the drawing a chart's `<c:userShapes>` cites.
18
+ */
19
+ export declare class EmbeddedPartEmitter extends Emitter<IEmbeddedPart.JSON> {
20
+ constructor();
21
+ /** @inheritdoc IEmitter.getContentType */
22
+ getContentType(part?: IEmbeddedPart.JSON): string;
23
+ /**
24
+ * @inheritdoc IEmitter.getRelTypeUri
25
+ *
26
+ * @remarks
27
+ * `''` with no part, since this emitter claims no relationship type of its own — it writes
28
+ * whatever the part it is handed says it is.
29
+ */
30
+ getRelTypeUri(part?: IEmbeddedPart.JSON): string;
31
+ /** @inheritdoc IEmitter.getPath */
32
+ getPath(part: IEmbeddedPart.JSON): string;
33
+ /** @inheritdoc IEmitter.emit */
34
+ emit(part: IEmbeddedPart.JSON, ctx: EmitContext): Promise<void>;
35
+ }
36
+ /**
37
+ * Adds a part's children to the package, each under the relationship id the part's own markup
38
+ * cites it by.
39
+ *
40
+ * @remarks
41
+ * Exported because the part at the top of a subtree is added by whoever holds it (a chart, by its
42
+ * anchor) rather than by this emitter, and its children still have to be written the same way.
43
+ */
44
+ export declare const writeChildren: (part: IEmbeddedPart.JSON, ctx: EmitContext) => Promise<void>;
45
+ /**
46
+ * Adds one carried part to the package, returning the relationship id it actually got.
47
+ *
48
+ * @remarks
49
+ * A part whose id could not be honored is reported by the caller rewriting the reference, not here:
50
+ * the markup that cites it is the caller's, and only the caller can rewrite it.
51
+ *
52
+ * `pathTemplate` is for the part at the top of a subtree, whose caller knows where its kind belongs
53
+ * (a chart under `xl/charts/`); everything below it is written beside its own parent, so naming the
54
+ * top names the lot.
55
+ *
56
+ * A part that is content rather than markup names its bytes by `resId`, resolved against
57
+ * {@link SHARED_STATE_RESOURCES_BY_ID} — complete before any part that could cite one emits.
58
+ */
59
+ export declare const writeEmbeddedPart: (part: IEmbeddedPart.JSON, ctx: EmitContext, pathTemplate?: string) => Promise<PackagePart | null>;
60
+ //# sourceMappingURL=EmbeddedPartEmitter.d.ts.map