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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/browser/esm/{Ctqql4O-3xj2K8vv.mjs → 2EOdn2WRK5y1L58S.mjs} +193 -143
  2. package/browser/esm/{BkNXyG6NC-w5Xo92.mjs → B-jb5SuiVh5NnBG_.mjs} +28 -13
  3. package/browser/esm/BKT8OBj-bhQwdg49.mjs +67 -0
  4. package/browser/esm/BLXcoiDAaOMjFuhw.mjs +8056 -0
  5. package/browser/esm/BPmehfSqdvgsLBsB.mjs +5153 -0
  6. package/browser/esm/CI_CZI5m5-KkiAK5.mjs +3559 -0
  7. package/browser/esm/{Dz1Dp8DDJvhd09RR.mjs → DXopGe8PrLWmwGaV.mjs} +1 -1
  8. package/browser/esm/NQIuOQIleHC4NUW6.mjs +2446 -0
  9. package/browser/esm/index.mjs +2 -3
  10. package/browser/esm/{CLWzJJyoSrykkVLX.mjs → xc_LzCPgHn-acgFZ.mjs} +2 -2
  11. package/licenses/dependencies.txt +2 -2
  12. package/node/esm/{fOnuUjpPCAzmuIXN.mjs → BmdmvgO5Zdgx-RWo.mjs} +2 -2
  13. package/node/esm/BpxxiZ2oKPkUSfdB.mjs +2486 -0
  14. package/node/esm/{CEV7nKotMpeRRnQC.mjs → CHqRP_NjPpPd7m9L.mjs} +1 -1
  15. package/node/esm/CtAF486aZqYzMeLM.mjs +3651 -0
  16. package/node/esm/{CEAmv36xpTNgFwl_.mjs → O5mti2R9drFOlXc7.mjs} +49 -35
  17. package/node/esm/QS_theNoeqNGLStj.mjs +5298 -0
  18. package/node/esm/index.mjs +40 -25
  19. package/node/esm/nNQ7MG89sGKwkjMA.mjs +4649 -0
  20. package/package.json +7 -8
  21. package/types/src/AutoFilterRules.d.ts +86 -10
  22. package/types/src/ConditionalFormatRules.d.ts +5 -5
  23. package/types/src/DataValidationRules.d.ts +18 -2
  24. package/types/src/ExcelCalcStamp.d.ts +39 -0
  25. package/types/src/ExcelCompat.d.ts +197 -42
  26. package/types/src/ExcelReservedNames.d.ts +3 -4
  27. package/types/src/LegacyFormula.d.ts +28 -7
  28. package/types/src/OOXMLExtensions.d.ts +14 -2
  29. package/types/src/Plugin.d.ts +16 -5
  30. package/types/src/ProtectionAttributes.d.ts +38 -0
  31. package/types/src/SourcePackage.d.ts +31 -12
  32. package/types/src/Types.d.ts +17 -0
  33. package/types/src/reader/HiddenFormulas.d.ts +16 -0
  34. package/types/src/reader/SlicerJoin.d.ts +24 -0
  35. package/types/src/reader/Warning.d.ts +29 -0
  36. package/types/src/reader/ZipReader.d.ts +1 -1
  37. package/types/src/reader/_SlicerRecord.d.ts +37 -0
  38. package/types/src/reader/dom/CustGeomUtils.d.ts +7 -0
  39. package/types/src/reader/dom/DOMTransformer.d.ts +2 -2
  40. package/types/src/reader/dom/ExecutionContext.d.ts +16 -3
  41. package/types/src/reader/dom/Types.d.ts +19 -3
  42. package/types/src/reader/domVisitors/AutoFilterVisitor.d.ts +13 -0
  43. package/types/src/reader/domVisitors/ColorContainerVisitor.d.ts +15 -2
  44. package/types/src/reader/domVisitors/CommentVisitor.d.ts +24 -2
  45. package/types/src/reader/domVisitors/CommentsVisitor.d.ts +2 -2
  46. package/types/src/reader/domVisitors/DrawingCxnSpVisitor.d.ts +1 -0
  47. package/types/src/reader/domVisitors/DrawingElementVisitor.d.ts +32 -1
  48. package/types/src/reader/domVisitors/DrawingGraphicFrameVisitor.d.ts +9 -0
  49. package/types/src/reader/domVisitors/DrawingGrpSpVisitor.d.ts +14 -2
  50. package/types/src/reader/domVisitors/DrawingPicVisitor.d.ts +13 -0
  51. package/types/src/reader/domVisitors/DrawingSpVisitor.d.ts +20 -1
  52. package/types/src/reader/domVisitors/DrawingVisitor.d.ts +10 -0
  53. package/types/src/reader/domVisitors/ExternalLinkVisitor.d.ts +21 -3
  54. package/types/src/reader/domVisitors/FmtSchemeVisitor.d.ts +4 -4
  55. package/types/src/reader/domVisitors/FormControlPrVisitor.d.ts +9 -0
  56. package/types/src/reader/domVisitors/ShapeTextVisitor.d.ts +44 -0
  57. package/types/src/reader/domVisitors/SheetColorContainerVisitor.d.ts +2 -2
  58. package/types/src/reader/domVisitors/SheetStyleVisitor.d.ts +19 -6
  59. package/types/src/reader/domVisitors/SlicerCacheDefinitionVisitor.d.ts +7 -2
  60. package/types/src/reader/domVisitors/SlicersVisitor.d.ts +7 -3
  61. package/types/src/reader/domVisitors/TextPropertiesVisitor.d.ts +13 -1
  62. package/types/src/reader/domVisitors/ThreadedCommentVisitor.d.ts +18 -1
  63. package/types/src/reader/domVisitors/ThreadedCommentsVisitor.d.ts +2 -2
  64. package/types/src/reader/domVisitors/WorkbookVisitor.d.ts +11 -1
  65. package/types/src/reader/domVisitors/index.d.ts +4 -2
  66. package/types/src/reader/sax/LeanSaxParser.d.ts +58 -0
  67. package/types/src/reader/sax/SaxParser.d.ts +11 -1
  68. package/types/src/reader/sax/SaxVisitor.d.ts +3 -2
  69. package/types/src/reader/saxVisitors/ContentTypesVisitor.d.ts +9 -0
  70. package/types/src/reader/saxVisitors/WorksheetVisitor.d.ts +11 -4
  71. package/types/src/utils/DrawingMLText.d.ts +39 -0
  72. package/types/src/utils/FormControls.d.ts +170 -0
  73. package/types/src/utils/VmlNoteShapes.d.ts +135 -0
  74. package/types/src/vba/VBAProject.d.ts +52 -4
  75. package/types/src/writer/builder/ContentTypes.d.ts +13 -0
  76. package/types/src/writer/builder/Emitter.d.ts +11 -6
  77. package/types/src/writer/builder/OpcXmlUtils.d.ts +2 -0
  78. package/types/src/writer/builder/PackageBuilder.d.ts +72 -22
  79. package/types/src/writer/builder/PartWriter.d.ts +5 -0
  80. package/types/src/writer/builder/RelationshipSet.d.ts +3 -0
  81. package/types/src/writer/builder/Types.d.ts +117 -38
  82. package/types/src/writer/builder/_Types.d.ts +17 -0
  83. package/types/src/writer/emitters/CommentsEmitter.d.ts +58 -0
  84. package/types/src/writer/emitters/EmbeddedPartEmitter.d.ts +60 -0
  85. package/types/src/writer/emitters/ExternalLinkEmitter.d.ts +19 -0
  86. package/types/src/writer/emitters/LegacyDrawingEmitter.d.ts +18 -0
  87. package/types/src/writer/emitters/PersonsEmitter.d.ts +17 -0
  88. package/types/src/writer/emitters/PivotTableEmitter.d.ts +45 -0
  89. package/types/src/writer/emitters/SlicerEmitter.d.ts +66 -0
  90. package/types/src/writer/emitters/StylesEmitter.d.ts +2 -2
  91. package/types/src/writer/emitters/TableEmitter.d.ts +14 -0
  92. package/types/src/writer/emitters/ThreadedCommentsEmitter.d.ts +27 -0
  93. package/types/src/writer/emitters/WorkbookEmitter.d.ts +16 -3
  94. package/types/src/writer/utils/AutoFilter.d.ts +2 -2
  95. package/types/src/writer/utils/CustGeomUtils.d.ts +5 -0
  96. package/types/src/writer/utils/DrawMLUtils.d.ts +57 -3
  97. package/types/src/writer/utils/DummyFunction.d.ts +0 -2
  98. package/types/src/writer/utils/DxfCollector.d.ts +3 -3
  99. package/types/src/writer/utils/HiddenFormulaXfs.d.ts +28 -0
  100. package/types/src/writer/utils/PrstGeomUtils.d.ts +6 -0
  101. package/types/src/writer/utils/TextUtils.d.ts +21 -2
  102. package/browser/cjs/B6sirGz6w-Bm7Ofo.cjs +0 -1
  103. package/browser/cjs/B7_pDFYCVzt-3hUs.cjs +0 -1
  104. package/browser/cjs/BAtEL-5TLyoaPFDP.cjs +0 -2
  105. package/browser/cjs/Bg0e53JZa8vhmm5a.cjs +0 -1
  106. package/browser/cjs/CIpMN7SDVREKQUQE.cjs +0 -6
  107. package/browser/cjs/CK5FFUvet6FnIYO_.cjs +0 -5
  108. package/browser/cjs/D5Y4KQhKdukOkjvA.cjs +0 -2
  109. package/browser/cjs/DV6LeTEiiFUrZoxj.cjs +0 -1
  110. package/browser/cjs/DWkuoJSgvcXJTdN1.cjs +0 -1
  111. package/browser/cjs/Db8YjGM6TG34c8aT.cjs +0 -1
  112. package/browser/cjs/index.cjs +0 -1
  113. package/browser/cjs/xQ6-wbTw5UzZUM1Y.cjs +0 -1
  114. package/browser/esm/4BWLu134ABlCQEtM.mjs +0 -3655
  115. package/browser/esm/BzQ_lPzc8C4OTIGZ.mjs +0 -99
  116. package/browser/esm/CJknI8BYGSZr-4zS.mjs +0 -52
  117. package/browser/esm/Cok_fBIUCHDSrKw0.mjs +0 -2211
  118. package/browser/esm/D-m_kQLaewdwuXaF.mjs +0 -2685
  119. package/browser/esm/Dj7D2nVdAZ3TiUks.mjs +0 -4743
  120. package/browser/esm/ijQzHH-bvDfUHIi1.mjs +0 -24
  121. package/node/esm/CF1R5ovFsRNu--Rw.mjs +0 -3744
  122. package/node/esm/Ctcl4jN52INWpKWC.mjs +0 -2255
  123. package/node/esm/CvnRSooxEQdlJgMn.mjs +0 -2766
  124. package/node/esm/DQd0vxzTaPt2qSL-.mjs +0 -108
  125. package/node/esm/ssSlRCbCqxvZ9IX8.mjs +0 -2481
  126. package/types/src/reader/domVisitors/HyperlinkVisitor.d.ts +0 -6
@@ -0,0 +1,39 @@
1
+ import { IFont, IShape, IText, ITextFrame } from '@sheetxl/sdk';
2
+ /**
3
+ * DrawingML's vocabulary for drawing text and shapes against SheetXL's: the attribute values a
4
+ * file states (`algn="ctr"`, `u="sng"`, `vert="eaVert"`) and the model values they read to.
5
+ *
6
+ * @remarks
7
+ * Every reader and writer of a `txBody`, a `cNvPr` or a drawing element goes through these
8
+ * tables, so a shape's text and a chart's title agree on what `center` is. A value neither side
9
+ * knows passes through unchanged: the file still reads back as written.
10
+ */
11
+ interface Vocabulary<M extends string> {
12
+ /** The model value for an attribute value. */
13
+ read(value: string): M;
14
+ /** The attribute value for a model value; `undefined` stays `undefined`. */
15
+ write(value: M | undefined): string | undefined;
16
+ }
17
+ /** The drawing element each kind of shape is written as, and reads from. */
18
+ export declare const SHAPE_TYPES: Readonly<Record<string, IShape.Type>>;
19
+ /** `pPr/@algn`. */
20
+ export declare const paragraphAlignment: Vocabulary<IText.ParagraphAlignment>;
21
+ /** `pPr/@fontAlgn`. */
22
+ export declare const fontAlignment: Vocabulary<IText.FontAlignment>;
23
+ /** `bodyPr/@anchor`. */
24
+ export declare const anchor: Vocabulary<ITextFrame.VerticalAlignment>;
25
+ /** `rPr/@u`. */
26
+ export declare const underline: Vocabulary<IText.UnderlineStyle>;
27
+ /** `rPr/@strike`. */
28
+ export declare const strike: Vocabulary<IText.StrikeStyle>;
29
+ /** `bodyPr/@vert`. */
30
+ export declare const writingMode: Vocabulary<ITextFrame.WritingMode>;
31
+ /** `bodyPr/@vertOverflow` and `@horzOverflow`. */
32
+ export declare const overflow: Vocabulary<ITextFrame.Overflow>;
33
+ /** `tab/@algn`. */
34
+ export declare const tabAlignment: Vocabulary<ITextFrame.TabStopAlignment>;
35
+ /** `latin/@charset` and its kin: a signed byte in the file, the `0-255` `LOGFONT` value in the model. */
36
+ export declare const readCharset: (value: string) => IFont.Charset | undefined;
37
+ export declare const writeCharset: (value: IFont.Charset | undefined) => string | undefined;
38
+ export {};
39
+ //# sourceMappingURL=DrawingMLText.d.ts.map
@@ -0,0 +1,170 @@
1
+ import { IFormControl, ICaptioned, IAnchored, Bounds, IMovable, ISheet, ITextFrame } from '@sheetxl/sdk';
2
+ /**
3
+ * A form control as Excel stores it, in and out of the model's form-control content types.
4
+ *
5
+ * @remarks
6
+ * Excel writes one control three times: a `ctrlProp` part (`<formControlPr>`) says what it is
7
+ * and what it holds; a shape in the sheet's VML draws it for Excel 2007; and a hidden `<xdr:sp>`
8
+ * in the drawing part — the *twin*, joined to the control by `a14:compatExt/@spid` — carries the
9
+ * caption and its font for Excel 2010 and later. The model holds one content per control, typed
10
+ * by kind ({@link IFormControl.Type}), and this module turns it into, and out of, all three.
11
+ *
12
+ * Excel 2010 and later read only the `<controls>` entry, the part and the twin: the VML shape is
13
+ * an echo they ignore and regenerate (its `<x:Checked>`, its caption, even its absence). So the
14
+ * shape is never carried: the reader takes it out of the sheet's VML, and the writer draws a new
15
+ * one from the model for the consumers that still read it (Excel 2007, LibreOffice). A file
16
+ * Excel 2007 wrote has no part and no `<controls>` entry at all, only the shape; that shape is
17
+ * read into a control ({@link readControlShape}) and written back in all three forms.
18
+ */
19
+ /** The x14 namespace the `ctrlProp` part declares. */
20
+ export declare const NS_FORM_CONTROL = "http://schemas.microsoft.com/office/spreadsheetml/2009/9/main";
21
+ /** The content type of a `ctrlProp` part. */
22
+ export declare const CONTENT_TYPE_CTRL_PROP = "application/vnd.ms-excel.controlproperties+xml";
23
+ /** The relationship a `<control>` uses for its `ctrlProp` part. */
24
+ export declare const RELATIONSHIP_TYPE_CTRL_PROP = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/ctrlProp";
25
+ /** The content types that are form controls, and so are written as Excel's `<controls>`. */
26
+ export declare const FORM_CONTROL_TYPES: ReadonlySet<string>;
27
+ /** Whether a movable's content is a form control. */
28
+ export declare const isFormControlType: (type: string | undefined) => boolean;
29
+ /**
30
+ * Reads a `<formControlPr>`, as its attributes, its list items and its `extLst` markup, into a
31
+ * content type and that kind's fields.
32
+ */
33
+ export declare function readFormControlPr(attributes: Record<string, string>, items: readonly string[], extLst: string | undefined): {
34
+ type: string;
35
+ json: IFormControl.JSON;
36
+ };
37
+ /**
38
+ * Writes a control's fields as a `ctrlProp` part.
39
+ */
40
+ export declare function writeFormControlPr(type: string, control: IFormControl.JSON): string;
41
+ /**
42
+ * Lifts the `<controlPr>` attributes the model names out of the attribute bag.
43
+ */
44
+ export declare function liftControlPr(props: Record<string, string>, control: IFormControl.JSON): void;
45
+ /**
46
+ * The `<controlPr>` attributes, the lifted ones restored.
47
+ */
48
+ export declare function controlPrAttributes(control: IFormControl.JSON): Record<string, string | undefined>;
49
+ /**
50
+ * What a hidden twin's shape JSON carries until `absorbControlTwins` takes it: the VML shape id
51
+ * of the control it draws for.
52
+ */
53
+ export interface ControlTwinMarks {
54
+ twinOf?: number;
55
+ }
56
+ /** What the drawing's hidden twin says about a control. */
57
+ export interface ControlTwin {
58
+ caption?: string;
59
+ font?: ICaptioned.Font;
60
+ }
61
+ /**
62
+ * Reads the caption and its font off a twin's text: the caption is the text, the font is the
63
+ * first run's.
64
+ */
65
+ export declare function readControlTwin(text: ITextFrame.JSON | undefined): ControlTwin;
66
+ /**
67
+ * Joins each drawing twin to the control it draws for, and takes it off the sheet.
68
+ *
69
+ * @remarks
70
+ * The twin is read as a hidden shape of its own (`DrawingSpVisitor`, which marks it with
71
+ * {@link ControlTwinMarks}); here it becomes the control's caption and font, and is written back
72
+ * from those (`controlTwinShape`). A twin whose control was not read stays the hidden shape it was.
73
+ *
74
+ * A twin inside a group is the control's place in it: Excel draws a grouped control at its twin's
75
+ * frame in the group, and its `<controls>` anchor only restates that on the sheet. So the member
76
+ * becomes the control, and the control read from `<controls>` leaves the sheet.
77
+ */
78
+ export declare function absorbControlTwins(sheet: ISheet.JSON): void;
79
+ /**
80
+ * The hidden `<xdr:sp>` the drawing part carries for a control, written from the model.
81
+ *
82
+ * @remarks
83
+ * Hidden, so the drawing layer never shows it; its `cNvPr/@id` is the shape id, as Excel's own
84
+ * is. The caption's font is restated as Excel restates it: size, weight and style on the run,
85
+ * the color as a solid fill, the family as `latin`.
86
+ *
87
+ * On the sheet the twin hangs from its anchor and states no frame; in a group it is the control's
88
+ * place in the group, so `frame` (pixels, in the group's child space) is written.
89
+ */
90
+ export declare function controlTwinShape(type: string, json: IFormControl.JSON, name: string | undefined, frame?: Bounds): string;
91
+ /**
92
+ * A control the sheet writes, wherever it is: on the sheet, or a member of a group, with where
93
+ * it sits in cells.
94
+ */
95
+ export interface SheetControl {
96
+ /** The control's movable, as the sheet's JSON or its group's holds it. */
97
+ jsonMovable: IMovable.JSON;
98
+ /** Its corners in cells. */
99
+ anchor: IMovable.AnchorOffset;
100
+ /** How it moves and sizes with its cells. */
101
+ anchorType: IAnchored.Type;
102
+ }
103
+ /**
104
+ * The sheet's controls, each in its `<controls>` place.
105
+ *
106
+ * @remarks
107
+ * A control on the sheet is where its anchor says. A grouped control is wherever its group draws
108
+ * it, which only the live model knows, so its corners are found from its drawn bounds; it moves
109
+ * and sizes as its group does. The JSON's movables are the sheet's (less notes) in order, and a
110
+ * group's members its own, in order.
111
+ */
112
+ export declare function sheetControls(sheet: ISheet, json: ISheet.JSON): SheetControl[];
113
+ /** The attributes an `mc:AlternateContent` around a twin's anchor declares. */
114
+ export declare const TWIN_ALTERNATE_CONTENT_ATTRIBUTES: {
115
+ 'xmlns:mc': string;
116
+ };
117
+ /** The attributes the `mc:Choice` inside it declares. */
118
+ export declare const TWIN_CHOICE_ATTRIBUTES: {
119
+ 'xmlns:a14': string;
120
+ Requires: string;
121
+ };
122
+ /** The shape id a VML shape names, or `null`. */
123
+ export declare function vmlShapeId(shape: string): number | null;
124
+ /** Whether a VML shape draws a form control (and not a note or a picture). */
125
+ export declare function isVmlControlShape(shape: string): boolean;
126
+ /**
127
+ * The VML part with every control shape visited: `update` answers the shape to keep, or `null`
128
+ * to drop it. Shapes that draw something else are left as they are.
129
+ */
130
+ export declare function mapVmlControlShapes(xml: string, update: (shape: string, shapeId: number | null) => string | null): string;
131
+ /** The shapetype every control shape refers to, declared once per part. */
132
+ export declare const CONTROL_SHAPETYPE = "<v:shapetype id=\"_x0000_t201\" coordsize=\"21600,21600\" o:spt=\"201\"\n path=\"m,l,21600r21600,l21600,xe\">\n <v:stroke joinstyle=\"miter\"/>\n <v:path shadowok=\"f\" o:extrusionok=\"f\" strokeok=\"f\" fillok=\"f\" o:connecttype=\"rect\"/>\n <o:lock v:ext=\"edit\" shapetype=\"t\"/>\n </v:shapetype>";
133
+ /**
134
+ * Where a control shape is written.
135
+ */
136
+ export interface ControlShapePlacement {
137
+ /** The number in `_x0000_s{n}`: the control's own shape id. */
138
+ shapeId: number;
139
+ zIndex: number;
140
+ /** The eight numbers of `<x:Anchor>`. */
141
+ anchor: readonly number[];
142
+ /** The control in pixels, for the `style` echo. */
143
+ bounds: Bounds;
144
+ anchorType: IAnchored.Type;
145
+ }
146
+ /**
147
+ * The VML shape that draws a control for the consumers that still read one, written from the
148
+ * model.
149
+ *
150
+ * @remarks
151
+ * Excel's own spelling, child for child, of a control it draws fresh. `<x:MoveWithCells/>` and
152
+ * `<x:SizeWithCells/>` are inverted in VML: present means the control does *not* follow its
153
+ * cells. Returns `null` for a kind the VML has no name for.
154
+ */
155
+ export declare function writeControlShape(type: string, control: IFormControl.JSON, placement: ControlShapePlacement): string | null;
156
+ /**
157
+ * A control read from its VML shape alone, as Excel 2007 stores one: no part, no `<controls>`
158
+ * entry. `null` when the shape is not a control or names no anchor.
159
+ *
160
+ * @remarks
161
+ * The anchor's offsets are the authoring machine's pixels and are taken as they are.
162
+ */
163
+ export declare function readControlShape(shape: string, shapeId: number | null): IMovable.JSON | null;
164
+ /**
165
+ * Takes every control shape out of the sheet's VML: a shape whose control was read from the
166
+ * sheet is dropped (the writer draws a new one), and one with no control is read into one
167
+ * ({@link readControlShape}). A part left with no shapes is dropped with them.
168
+ */
169
+ export declare function absorbControlShapes(sheet: ISheet.JSON): void;
170
+ //# sourceMappingURL=FormControls.d.ts.map
@@ -0,0 +1,135 @@
1
+ /**
2
+ * The note boxes in a sheet's VML drawing: finding them, keeping them apart from the control
3
+ * shapes that share the part, reading each into what a note stores, and writing one for every
4
+ * comment.
5
+ *
6
+ * @remarks
7
+ * A note's box is a `<v:shape>` whose `<x:ClientData ObjectType="Note">` names its cell in
8
+ * `<x:Row>`/`<x:Column>` (0-based), and its corners in `<x:Anchor>` as four cell/offset pairs
9
+ * (left cell, left offset, top cell, top offset, right cell, right offset, bottom cell, bottom
10
+ * offset). Nothing else in the VML names a note, so the cell is the join to the comment.
11
+ *
12
+ * The anchor alone places a box (the `style` margins are an echo Excel regenerates), and
13
+ * `<x:Visible/>` alone shows it. So a shape is read into those two and the rest of its markup,
14
+ * and what is left is the same for every note Excel made and never formatted. That markup is kept
15
+ * only when it is not Excel's default, and the id, the anchor, the cell and the `style` echo are
16
+ * written from the model.
17
+ *
18
+ * A form control's shape is in the same part, and is taken out of it and drawn again the same
19
+ * way (`FormControls.ts`). The difference is the id: nothing refers to a note's, so it is minted
20
+ * on write, while a `<control shapeId>` names its shape's and has to keep it.
21
+ */
22
+ /** A note shape as read: its markup and the cell it was on. */
23
+ export interface NoteShape {
24
+ xml: string;
25
+ row: number;
26
+ col: number;
27
+ }
28
+ /**
29
+ * What a note shape says, apart from the cell it is on.
30
+ */
31
+ export interface NoteShapeBox {
32
+ /**
33
+ * The eight numbers of `<x:Anchor>`, or `null` when the shape has none that can be read.
34
+ */
35
+ anchor: number[] | null;
36
+ /** Whether the shape has `<x:Visible/>`: the box stays on the sheet. */
37
+ visible: boolean;
38
+ /** The shape's alternative text. */
39
+ alt: string | null;
40
+ /**
41
+ * The shape without its id, position, cell or alternative text, or `null` when that is
42
+ * Excel's default shape.
43
+ */
44
+ xml: string | null;
45
+ }
46
+ /**
47
+ * Where a note shape is written.
48
+ */
49
+ export interface NoteShapePlacement {
50
+ /** The number in `_x0000_s{n}`. */
51
+ shapeId: number;
52
+ zIndex: number;
53
+ /** 0-based. */
54
+ row: number;
55
+ /** 0-based. */
56
+ col: number;
57
+ /** The eight numbers of `<x:Anchor>`. */
58
+ anchor: readonly number[];
59
+ /** The box in pixels, for the `style` echo. */
60
+ bounds: {
61
+ x: number;
62
+ y: number;
63
+ width: number;
64
+ height: number;
65
+ };
66
+ visible: boolean;
67
+ alt?: string | null;
68
+ }
69
+ /**
70
+ * Splits the note shapes out of a VML part.
71
+ *
72
+ * @returns The part with the note shapes removed (`rest`), and the shapes with their cells.
73
+ * `rest` keeps the shapetype declarations, the control shapes and the closing root exactly as
74
+ * they were, so a part with no notes comes back byte for byte.
75
+ */
76
+ export declare function splitNoteShapes(xml: string): {
77
+ rest: string;
78
+ notes: NoteShape[];
79
+ };
80
+ /**
81
+ * Whether the part has any shape at all once its note boxes are taken out — a part that is only
82
+ * the root and the shapetype declarations has nothing left to say.
83
+ */
84
+ export declare function hasShapes(xml: string): boolean;
85
+ /**
86
+ * A note shape without what the model writes: its id, its anchor and the `style` that echoes
87
+ * it, its cell, whether it is shown and its alternative text. Whitespace between elements is
88
+ * dropped, so two shapes that say the same thing are the same string.
89
+ *
90
+ * @returns The markup, or `null` when it is not a shape.
91
+ */
92
+ export declare function normalizeNoteShape(xml: string): string | null;
93
+ /**
94
+ * The shape Excel gives a note that has not been formatted, normalized.
95
+ */
96
+ export declare const DEFAULT_NOTE_SHAPE: string;
97
+ /**
98
+ * Reads a note shape into what a note stores.
99
+ */
100
+ export declare function readNoteShape(xml: string): NoteShapeBox;
101
+ /** A pixel length in points, as Excel writes one: no trailing zeros. */
102
+ export declare const toPt: (px: number) => string;
103
+ /**
104
+ * A note shape for a comment: the markup it carries, or Excel's default, with its id, its
105
+ * position and its cell written in.
106
+ *
107
+ * @param markup A shape as {@link normalizeNoteShape} leaves it, or `null` for the default. One
108
+ * that was not normalized is normalized first.
109
+ */
110
+ export declare function writeNoteShape(markup: string | null | undefined, placement: NoteShapePlacement): string;
111
+ /**
112
+ * The largest shape number the part uses, so a written shape can take the next.
113
+ *
114
+ * @remarks
115
+ * A part with no shapes starts from the block its `<o:idmap>` claims: ids come in blocks of
116
+ * 1024, and Excel gives each sheet's drawing a block of its own.
117
+ */
118
+ export declare function maxShapeId(xml: string): number;
119
+ /** The shapetype every note box refers to, declared once per part. */
120
+ export declare const NOTE_SHAPETYPE = "<v:shapetype id=\"_x0000_t202\" coordsize=\"21600,21600\" o:spt=\"202\"\n path=\"m,l,21600r21600,l21600,xe\">\n <v:stroke joinstyle=\"miter\"/>\n <v:path gradientshapeok=\"t\" o:connecttype=\"rect\"/>\n </v:shapetype>";
121
+ /** An empty VML part, for a sheet whose notes have no drawing to be added to. */
122
+ export declare const EMPTY_LEGACY_DRAWING = "<xml xmlns:v=\"urn:schemas-microsoft-com:vml\"\n xmlns:o=\"urn:schemas-microsoft-com:office:office\"\n xmlns:x=\"urn:schemas-microsoft-com:office:excel\">\n <o:shapelayout v:ext=\"edit\">\n <o:idmap v:ext=\"edit\" data=\"1\"/>\n </o:shapelayout></xml>";
123
+ /**
124
+ * The part with shapes put back before the closing root: note boxes, or the shapes of another
125
+ * kind given its `shapetype`.
126
+ *
127
+ * @param lastShapeId The largest shape number among `shapes`, so the part can claim its block.
128
+ * @param shapetype The declaration `shapes` refer to; the note box's by default.
129
+ *
130
+ * @remarks
131
+ * The shapetype is declared once if any shape needs it and the part does not already declare
132
+ * it. A part that ends up with no shapes at all returns `null`: nothing to write.
133
+ */
134
+ export declare function assembleLegacyDrawing(rest: string | null, shapes: string[], lastShapeId?: number, shapetype?: string): string | null;
135
+ //# sourceMappingURL=VmlNoteShapes.d.ts.map
@@ -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";
@@ -5,20 +5,25 @@ export declare abstract class Emitter<T = any> implements IEmitter<T> {
5
5
  protected _contentType: string;
6
6
  protected _relTypeUri: string;
7
7
  protected _path: string | ((instance: T) => string) | undefined;
8
+ protected _regeneratesRelationships: boolean;
8
9
  constructor(options: {
9
10
  kind: string;
10
11
  contentType: string;
11
12
  relTypeUri: string;
12
13
  path?: string | ((instance: T) => string);
14
+ /** {@inheritdoc IEmitter.regeneratesRelationships} */
15
+ regeneratesRelationships?: boolean;
13
16
  });
17
+ /** @inheritdoc IEmitter.regeneratesRelationships */
18
+ regeneratesRelationships(): boolean;
14
19
  /** @inheritdoc IEmitter.emit */
15
20
  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;
21
+ /** @inheritdoc IEmitter.getKind */
22
+ getKind(): string;
23
+ /** @inheritdoc IEmitter.getContentType */
24
+ getContentType(_instance?: T): string;
25
+ /** @inheritdoc IEmitter.getRelTypeUri */
26
+ getRelTypeUri(_instance?: T): string;
22
27
  /** @inheritdoc IEmitter.getPath */
23
28
  getPath(instance: T): string;
24
29
  }
@@ -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;
@@ -59,13 +59,36 @@ export declare class PackageBuilder<Out> {
59
59
  private _scheduledByNodeKey;
60
60
  private _nodesByPath;
61
61
  private _writtenPaths;
62
+ /** Claimed paths whose emitter regenerates every relationship ({@link IEmitter.regeneratesRelationships}). */
63
+ private _regeneratedPaths;
62
64
  private _partWriter;
63
65
  private _registry;
64
66
  private _options;
65
67
  private _sourcePackage;
68
+ /** See {@link PackageBuilderOptions.macroEnabled}. */
69
+ private _macroEnabled;
66
70
  private _explicitRelTargets;
67
71
  private _mapState;
68
72
  constructor(zip: IZipBackend<Out>, registry: EmitterRegistry, options?: PackageBuilderOptions);
73
+ /**
74
+ * Whether a source part named `name` will be in this package once {@link _passthroughSourceParts}
75
+ * has run — the drop rules of `DESIGN-PACKAGE-PASSTHROUGH.md` §4, as one predicate. `false` when
76
+ * there is no source package or it has no such part.
77
+ *
78
+ * @remarks
79
+ * Does not consider whether an emitter claimed the *path* — that part is then in the package, but
80
+ * as the emitter's, not the source's. It does consider whether the reader took the part onto the
81
+ * model ({@link ISourcePackage.isAbsorbed}), which is a different question: the model writes that
82
+ * part wherever its own numbering puts it, which need not be where the source had it.
83
+ */
84
+ private _isSourcePartCarried;
85
+ /**
86
+ * Hold the source's own relationship ids back in `partPath`'s set, before the emitter rewriting
87
+ * that part allocates anything — see {@link IRelationshipSet.reserve}. The emitter's edges then
88
+ * go above them, and a source edge {@link _mergeSourceRelsInto} carries back in afterwards keeps
89
+ * its name, which is what a captured source fragment replayed inside the part still cites.
90
+ */
91
+ private _reserveSourceRelIds;
69
92
  /**
70
93
  * Wait for all scheduled parts to be emitted.
71
94
  */
@@ -88,13 +111,51 @@ export declare class PackageBuilder<Out> {
88
111
  */
89
112
  private _passthroughSourceParts;
90
113
  /**
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.
114
+ * Declare the workbook part's macro-enabled **variant** of `CT_Workbook` when the package being
115
+ * built is one — the difference between `…spreadsheetml.sheet.main+xml` and
116
+ * `…ms-excel.sheet.macroEnabled.main+xml`.
117
+ *
118
+ * @remarks
119
+ * `xl/workbook.xml` is emitter-claimed, and its emitter declares the plain variant unconditionally
120
+ * because macro-enabledness is not a property of the workbook — it is a property of the format
121
+ * being written to, which no emitter can see. Without this a macro workbook would be saved
122
+ * carrying a VBA project it no longer admits to: the payload preserved and every statement about
123
+ * it wrong.
124
+ *
125
+ * The decision is {@link PackageBuilderOptions.macroEnabled}, i.e. purely the resolved write
126
+ * format, and the **same flag also decides whether the project part is carried**
127
+ * ({@link _passthroughSourceParts}). Deriving both from one input is what makes it impossible for
128
+ * the declaration and the payload to disagree — the earlier attempt inferred the variant from the
129
+ * source package instead, which got an `.xlsm`-to-`.xlsx` export wrong in both halves at once.
130
+ *
131
+ * Independent of whether a project is actually present: a macro-enabled workbook containing no
132
+ * VBA at all is a legal thing for Excel to produce, and demoting it would silently change the
133
+ * file type the user asked for.
134
+ *
135
+ * Scoped to the workbook part on purpose. A blanket "source Override wins for claimed parts"
136
+ * would let a stale declaration through on anything.
137
+ */
138
+ private _applyWorkbookContentTypeVariant;
139
+ /**
140
+ * Seed `sourcePart`'s {@link IRelationshipSet} with the source's edges, each under the source's
141
+ * own id. Targets are carried forward as-is (still relative to the same referencing part, at the
142
+ * same OPC path) — nothing to recompute.
143
+ *
144
+ * @remarks
145
+ * Which edges come back depends on who wrote the part (`DESIGN-PACKAGE-PASSTHROUGH.md` §6):
146
+ *
147
+ * - A **preserved** part is the source's bytes, so its XML still cites the ids the source's
148
+ * `.rels` defined; every edge whose target is still in the package comes back with that id.
149
+ * Nothing else ever wrote into this set, so the ids are free.
150
+ * - A **rewritten** part (the root, or one an emitter claimed) had its emitter recreate the edges
151
+ * it cites, so only what the emitter did not recreate is added: not an edge whose target an
152
+ * emitter claimed (its own, correct edge exists already — keeping both would duplicate it), not
153
+ * one added by name through `addRelationship`. The set had the source's ids reserved before
154
+ * the emitter allocated ({@link _reserveSourceRelIds}), so these too keep their names —
155
+ * unless an emitter took the id as a hint for a different target, in which case it is fresh.
156
+ *
157
+ * An edge whose target did not survive at all is dropped either way (§5). A `TargetMode="External"`
158
+ * or `#`-fragment target is not a part and is never resolved as one.
98
159
  */
99
160
  private _mergeSourceRelsInto;
100
161
  /**
@@ -104,8 +165,8 @@ export declare class PackageBuilder<Out> {
104
165
  * @param instance The instance of the part to add.
105
166
  * @returns The path of the added root part.
106
167
  */
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;
168
+ addPart<T = any>(kind: string, instance: T, pathTemplate?: string, idHint?: string): PackagePart;
169
+ protected _addPartInternal<T = any>(currentPartPath: string, kind: string, instance: T, pathTemplate?: string, idHint?: string): PackagePart;
109
170
  /**
110
171
  * Add a binary to the package.
111
172
  *
@@ -119,19 +180,8 @@ export declare class PackageBuilder<Out> {
119
180
  * @remarks
120
181
  * Override is only used if the path is not a template
121
182
  */
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;
183
+ addBinary(bytes: Uint8Array, contentType: string, relTypeUri: string, pathTemplate: string, override?: boolean, idHint?: string): PackagePart;
184
+ protected _addBinaryInternal(currentPartPath: string, bytes: Uint8Array, contentType: string, relTypeUri: string, pathTemplate: string, override?: boolean, idHint?: string): PackagePart;
135
185
  protected _waitForDescendants(parentPath: string): Promise<void>;
136
186
  protected _processPart(node: Scheduled): Promise<void>;
137
187
  }
@@ -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;