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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/browser/cjs/BzOEBR0jaxXg9wvt.cjs +5 -0
  2. package/browser/cjs/C8oC1tPbhgR0Dqtx.cjs +2 -0
  3. package/browser/cjs/Ca-xJDjg5bOpUPXX.cjs +1 -0
  4. package/browser/cjs/{D5Y4KQhKdukOkjvA.cjs → D3EWCPfCu-qMOIGd.cjs} +1 -2
  5. package/browser/cjs/{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/B9q618XELV7uWJsA.mjs +67 -0
  10. package/browser/esm/{Dj7D2nVdAZ3TiUks.mjs → BwbMurFOptAFs7gC.mjs} +1595 -1124
  11. package/browser/esm/{CLWzJJyoSrykkVLX.mjs → CMHb6pUUmsCP9r_9.mjs} +2 -2
  12. package/browser/esm/{ijQzHH-bvDfUHIi1.mjs → CMzkLUwbgA73RvCb.mjs} +1 -1
  13. package/browser/esm/D75_rfogFUfXADKc.mjs +3324 -0
  14. package/browser/esm/{4BWLu134ABlCQEtM.mjs → DfuBawaydlvgZMR-.mjs} +1824 -1051
  15. package/browser/esm/{BkNXyG6NC-w5Xo92.mjs → DhqYgh9G2vLn7mIE.mjs} +28 -13
  16. package/browser/esm/DoMlKUCnMSlR2qX5.mjs +159 -0
  17. package/browser/esm/{Cok_fBIUCHDSrKw0.mjs → DtpWa7tZahylJ3HS.mjs} +446 -347
  18. package/browser/esm/{Ctqql4O-3xj2K8vv.mjs → IZf0hIeLYj3T0Xvu.mjs} +2 -2
  19. package/browser/esm/{Dz1Dp8DDJvhd09RR.mjs → _UDbQq5-pHbU1f82.mjs} +1 -1
  20. package/browser/esm/index.mjs +3 -3
  21. package/node/esm/{CF1R5ovFsRNu--Rw.mjs → BD03jrMQ_UKA196-.mjs} +1934 -1143
  22. package/node/esm/{fOnuUjpPCAzmuIXN.mjs → Bi_kZVtZams7taqa.mjs} +2 -2
  23. package/node/esm/{Ctcl4jN52INWpKWC.mjs → BxHvzSROx_N_7nJH.mjs} +607 -506
  24. package/node/esm/{CEAmv36xpTNgFwl_.mjs → CB1ijGbhl-e2l6Mm.mjs} +49 -35
  25. package/node/esm/CO1M1H1N6fB422K-.mjs +2959 -0
  26. package/node/esm/CWpezSa6TERGEv-B.mjs +3410 -0
  27. package/node/esm/{CEV7nKotMpeRRnQC.mjs → CY-pSutJLHskZfXZ.mjs} +1 -1
  28. package/node/esm/Dezt2uIDqlxjiuk5.mjs +170 -0
  29. package/node/esm/index.mjs +40 -25
  30. package/package.json +3 -3
  31. package/types/src/ConditionalFormatRules.d.ts +3 -3
  32. package/types/src/DataValidationRules.d.ts +18 -2
  33. package/types/src/ExcelCalcStamp.d.ts +39 -0
  34. package/types/src/ExcelCompat.d.ts +197 -42
  35. package/types/src/LegacyFormula.d.ts +28 -7
  36. package/types/src/Plugin.d.ts +16 -5
  37. package/types/src/ProtectionAttributes.d.ts +38 -0
  38. package/types/src/SourcePackage.d.ts +31 -12
  39. package/types/src/Types.d.ts +17 -0
  40. package/types/src/reader/HiddenFormulas.d.ts +16 -0
  41. package/types/src/reader/Warning.d.ts +29 -0
  42. package/types/src/reader/dom/DOMTransformer.d.ts +1 -1
  43. package/types/src/reader/dom/ExecutionContext.d.ts +16 -3
  44. package/types/src/reader/dom/Types.d.ts +19 -3
  45. package/types/src/reader/domVisitors/CommentVisitor.d.ts +18 -1
  46. package/types/src/reader/domVisitors/CommentsVisitor.d.ts +2 -2
  47. package/types/src/reader/domVisitors/ExternalLinkVisitor.d.ts +21 -3
  48. package/types/src/reader/domVisitors/SheetColorContainerVisitor.d.ts +2 -2
  49. package/types/src/reader/domVisitors/SheetStyleVisitor.d.ts +6 -1
  50. package/types/src/reader/domVisitors/ThreadedCommentVisitor.d.ts +9 -1
  51. package/types/src/reader/domVisitors/ThreadedCommentsVisitor.d.ts +2 -2
  52. package/types/src/reader/domVisitors/WorkbookVisitor.d.ts +11 -1
  53. package/types/src/reader/sax/LeanSaxParser.d.ts +58 -0
  54. package/types/src/reader/sax/SaxParser.d.ts +11 -1
  55. package/types/src/reader/sax/SaxVisitor.d.ts +3 -2
  56. package/types/src/reader/saxVisitors/ContentTypesVisitor.d.ts +9 -0
  57. package/types/src/reader/saxVisitors/WorksheetVisitor.d.ts +11 -4
  58. package/types/src/utils/VmlNoteShapes.d.ts +75 -0
  59. package/types/src/vba/VBAProject.d.ts +52 -4
  60. package/types/src/writer/builder/ContentTypes.d.ts +13 -0
  61. package/types/src/writer/builder/Emitter.d.ts +6 -6
  62. package/types/src/writer/builder/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
@@ -1,4 +1,5 @@
1
- import { IComment } from '@sheetxl/sdk';
1
+ import { IPerson, IEmbeddedPart } from '@sheetxl/sdk';
2
+ import { OnWarning } from '../Warning';
2
3
  export interface RelationShipType {
3
4
  target?: string;
4
5
  type?: string;
@@ -19,9 +20,24 @@ export interface TransformerOptions {
19
20
  };
20
21
  getRefs?: (refLocation: string, parsedRefs?: Map<string, Map<string, RelationShipType>>) => Map<string, RelationShipType>;
21
22
  parsedRefs?: Map<string, any>;
22
- onWarning?: (message: string) => void;
23
- addPerson?: (person: Partial<IComment.PersonJSON>) => IComment.PersonJSON;
23
+ /** Where the warnings this transform raises are reported. See {@link OnWarning}. */
24
+ onWarning?: OnWarning;
25
+ addPerson?: (person: Partial<IPerson.JSON>) => IPerson.JSON;
24
26
  /** Serializes a parsed DOM element back to an XML string, verbatim. Used to capture unmodeled content. */
25
27
  serializeElement?: (elem: Element) => string;
28
+ /**
29
+ * Resolves a relationship to the part it names and, recursively, the parts that part references,
30
+ * as content to be carried on the model and written back unchanged.
31
+ *
32
+ * @remarks
33
+ * The other half of {@link TransformerOptions.getRef}, not a variant of it. `getRef` *interprets*:
34
+ * it dispatches on the relationship type and hands back a sheet, an external book, a resource id
35
+ * — whatever the reader models that part as. This hands back the part itself: its markup as text,
36
+ * its bytes as a resource, and the same again for everything it references, none of it read. Use
37
+ * `getRef` for a part the model understands and this for one it only has to keep.
38
+ *
39
+ * See `readEmbeddedPart` in `XLSXReader` for what it costs and why it is not a visitor's job.
40
+ */
41
+ readEmbeddedPart?: (relId: string, refLocation: string) => IEmbeddedPart.JSON | null;
26
42
  }
27
43
  //# sourceMappingURL=Types.d.ts.map
@@ -1,6 +1,23 @@
1
1
  import { IRange, IComment } from '@sheetxl/sdk';
2
2
  import { Visitor, ExecutionContext } from '../dom';
3
+ /**
4
+ * One `<comment>` of a legacy comments part, as read: its author as an index into the part's
5
+ * `<authors>`, and its rich text.
6
+ */
7
+ export interface LegacyNoteEntry {
8
+ authorId?: number;
9
+ content: IComment.Content;
10
+ }
11
+ /**
12
+ * `<comment ref authorId>` with its `<text>`: the runs are SpreadsheetML rich text — `<r>` with
13
+ * an `<rPr>` of child elements (`<b/>`, `<sz val>`, `<rFont val>`, `<color rgb>`) — read here
14
+ * rather than by the DrawingML text visitor, whose properties are attributes.
15
+ */
3
16
  export declare class CommentVisitor implements Visitor {
4
- visit(context: ExecutionContext, elem: Element, jsonParent: IRange.JSONReferenceEntry<IComment.RichJSON>[]): any;
17
+ visit(context: ExecutionContext, elem: Element, jsonParent: IRange.JSONReferenceEntry<LegacyNoteEntry>[]): any;
5
18
  }
19
+ /**
20
+ * The runs of a `<text>`, as a string when none carries formatting.
21
+ */
22
+ export declare function readRichText(textElement: Element | null): IComment.Content;
6
23
  //# sourceMappingURL=CommentVisitor.d.ts.map
@@ -1,7 +1,7 @@
1
- import { IRange, IComment } from '@sheetxl/sdk';
1
+ import { IRange } from '@sheetxl/sdk';
2
2
  import { Visitor, ExecutionContext } from '../dom';
3
3
  export declare class CommentsVisitor implements Visitor {
4
- visit(context: ExecutionContext, elemParent: Element, jsonParent: any): IRange.JSONReferenceEntry<IComment.JSON>[] | undefined;
4
+ visit(context: ExecutionContext, elemParent: Element, jsonParent: any): IRange.JSONReferenceEntry<any>[] | undefined;
5
5
  processAuthors(context: ExecutionContext, elem: Element, authors: string[]): void;
6
6
  }
7
7
  //# sourceMappingURL=CommentsVisitor.d.ts.map
@@ -9,12 +9,12 @@ import { Visitor, ExecutionContext } from '../dom';
9
9
  * for the other two `jsonParent` is left untouched (empty), which the reader normalizes to `null`
10
10
  * — DDE/OLE are never modeled, and package passthrough covers their bytes separately.
11
11
  *
12
- * The book's identity — the ordered `(relTypeUri, target)` list from the part's OWN `.rels` file —
12
+ * The book's sources — the ordered `(relTypeUri, target)` list from the part's OWN `.rels` file —
13
13
  * is deliberately not read here: a visitor only ever sees its own part's XML, never a sibling rels
14
- * file. `XLSXReader` attaches `identity` after this visitor returns.
14
+ * file. `XLSXReader` attaches `sources` after this visitor returns.
15
15
  */
16
16
  export declare class ExternalLinkVisitor implements Visitor {
17
- visit(context: ExecutionContext, elem: Element, jsonParent: Partial<IExternalBook.JSON>): Partial<IExternalBook.JSON>;
17
+ visit(context: ExecutionContext, elem: Element, jsonParent: Partial<IExternalBook.JSON> & ExternalLinkVisitor.RelIds): Partial<IExternalBook.JSON>;
18
18
  processSheetNames(context: ExecutionContext, elemBook: Element, jsonBook: IExternalBook.JSON): void;
19
19
  processDefinedNames(context: ExecutionContext, elemBook: Element, jsonBook: IExternalBook.JSON): void;
20
20
  processSheetDataSet(context: ExecutionContext, elemBook: Element, jsonBook: IExternalBook.JSON): void;
@@ -28,5 +28,23 @@ export declare class ExternalLinkVisitor implements Visitor {
28
28
  */
29
29
  private _readCellValue;
30
30
  private _findChild;
31
+ /** `<xxl21:alternateUrls><xxl21:absoluteUrl r:id="rIdN"/></xxl21:alternateUrls>` — design doc §2.2. */
32
+ private _findAbsoluteUrlRelId;
33
+ }
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
+ interface RelIds {
46
+ __bookRelId?: string;
47
+ __absoluteUrlRelId?: string;
48
+ }
31
49
  }
32
50
  //# sourceMappingURL=ExternalLinkVisitor.d.ts.map
@@ -1,4 +1,4 @@
1
- import { IFill, IBorder, IStyledFont } from '@sheetxl/sdk';
1
+ import { IFill, IBorders, IStyledFont } from '@sheetxl/sdk';
2
2
  import { Visitor, ExecutionContext } from '../dom';
3
3
  export declare class SheetColorContainerVisitor implements Visitor {
4
4
  visit(_context: ExecutionContext, _elemParent: Element, _jsonParent: any): any;
@@ -23,6 +23,6 @@ export declare class SheetColorContainerVisitor implements Visitor {
23
23
  * border definitions. In both SheetXL and Excel these values are ignored.
24
24
  */
25
25
  processBorder(context: ExecutionContext, elem: Element, jsonParent: any, index: number, tile: boolean): any;
26
- processBorderStroke(context: ExecutionContext, elem: Element, jsonParent: IBorder.JSON, edge: IBorder.Edge): any;
26
+ processBorderStroke(context: ExecutionContext, elem: Element, jsonParent: IBorders.JSON, edge: IBorders.Edge): any;
27
27
  }
28
28
  //# sourceMappingURL=SheetColorContainerVisitor.d.ts.map
@@ -9,10 +9,15 @@ export declare class SheetStyleVisitor extends SheetColorContainerVisitor implem
9
9
  processXFs(context: ExecutionContext, elem: Element, jsonParent: IStyle.JSON[], denormalized: any, namedIds?: Map<number, string> | null, ignoreApplys?: boolean): any;
10
10
  processXF(context: ExecutionContext, elem: Element, jsonParent: IStyle.JSON, denormalized: any, namedIds: Map<number, string> | null, ignoreApplys: boolean): any;
11
11
  processAlignment(context: ExecutionContext, elem: Element, jsonParent: any): any;
12
+ /**
13
+ * The cell xfs whose `<protection>` says `hidden="1"`. They become the sheet's `showFormulas` once
14
+ * the sheets are read (`applyHiddenFormulas`), since a format alone cannot say it.
15
+ */
16
+ collectHiddenXfs(elem: Element): Set<number>;
12
17
  processProtection(context: ExecutionContext, elem: Element, jsonParent: any): any;
13
18
  processDXF(context: ExecutionContext, elem: Element, jsonParent: IStyle.JSON): any;
14
19
  processDXFs(context: ExecutionContext, elem: Element, jsonParent: any[]): any;
15
- processTableStyle(_context: ExecutionContext, elem: Element, jsonParent: any, dxfs: any[], shiftTableDx?: boolean): any;
20
+ processTableStyle(context: ExecutionContext, elem: Element, jsonParent: any, dxfs: any[], shiftTableDx?: boolean): any;
16
21
  processTableStyles(context: ExecutionContext, elem: Element, jsonParent: any, dxfs: any[], shiftTableDx?: boolean): any;
17
22
  processCellStyles(context: ExecutionContext, elem: Element, named: IStyle.NamedJSON[], namedXfs: IStyle.JSON[], namedIds: Map<number, string>): any;
18
23
  afterVisit(_context: ExecutionContext, _elem: Element, _json: any): void;
@@ -1,9 +1,17 @@
1
1
  import { IRange, IComment } from '@sheetxl/sdk';
2
2
  import { Visitor, ExecutionContext } from '../dom';
3
+ /**
4
+ * One `<threadedComment>` as read: a root or a reply, flat, joined to its thread by `parentId`.
5
+ * The reader nests replies under their roots.
6
+ */
7
+ export interface ThreadedEntry extends IComment.EntryJSON {
8
+ parentId?: string;
9
+ done?: boolean;
10
+ }
3
11
  /**
4
12
  * https://learn.microsoft.com/en-us/openspecs/office_standards/ms-xlsx/adb84732-9fc8-48b6-bddc-6b0bcdaad940
5
13
  */
6
14
  export declare class ThreadedCommentVisitor implements Visitor {
7
- visit(context: ExecutionContext, elem: Element, jsonParent: IRange.JSONReferenceEntry<IComment.RichJSON>[]): IComment.RichJSON | undefined;
15
+ visit(context: ExecutionContext, elem: Element, jsonParent: IRange.JSONReferenceEntry<ThreadedEntry>[]): ThreadedEntry | undefined;
8
16
  }
9
17
  //# sourceMappingURL=ThreadedCommentVisitor.d.ts.map
@@ -1,6 +1,6 @@
1
- import { IRange, IComment, ISheet } from '@sheetxl/sdk';
1
+ import { IRange, ISheet } from '@sheetxl/sdk';
2
2
  import { Visitor, ExecutionContext } from '../dom';
3
3
  export declare class ThreadedCommentsVisitor implements Visitor {
4
- visit(context: ExecutionContext, elem: Element, jsonParent: ISheet.JSON): IRange.JSONReferenceEntry<IComment.JSON>[] | undefined;
4
+ visit(context: ExecutionContext, elem: Element, jsonParent: ISheet.JSON): IRange.JSONReferenceEntry<any>[] | undefined;
5
5
  }
6
6
  //# sourceMappingURL=ThreadedCommentsVisitor.d.ts.map
@@ -17,9 +17,19 @@ export declare class WorkbookVisitor extends SheetColorContainerVisitor {
17
17
  * `context.getRef` resolves through the generic `readAsJSON` path, which dispatches to
18
18
  * `ExternalLinkVisitor` by the target part's root element — `null` for a DDE/OLE part (not ours
19
19
  * to read) or a missing rel, keeping the position without a book's content (see `XLSXReader`'s
20
- * `getRef`, which normalizes an empty visitor result to `null` and attaches `identity`).
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
+ processPivotCaches(context: ExecutionContext, elem: Element, jsonParent: IWorkbook.JSON): any;
23
33
  processBookViews(context: ExecutionContext, elem: Element, jsonParent: IWorkbook.JSON): any;
24
34
  processWorkbookView(context: ExecutionContext, elem: Element, jsonParent: IWorkbook.JSON): any;
25
35
  processDefineName(context: ExecutionContext, elem: Element, jsonNames: INamedCollection.JSON, sheets: IWorkbook.SheetRefJSON[]): any;
@@ -0,0 +1,58 @@
1
+ import { SaxesTag } from './Saxes';
2
+ export type LeanSaxEvent = 'opentag' | 'closetag' | 'text' | 'cdata' | 'error' | 'end';
3
+ /**
4
+ * Takes over one element name from the tokenizer. For a hot element with a fixed shape (a
5
+ * worksheet `<c>`), reading the raw text directly skips the tag and attribute objects the generic
6
+ * events need, which is most of the tokenizer's cost.
7
+ */
8
+ export interface ElementScanner {
9
+ /** The raw (prefixed, if the part uses a prefix) tag name this scanner takes. */
10
+ readonly name: string;
11
+ /**
12
+ * When set, {@link scan} consumes only the START tag of a non-self-closing element, and the
13
+ * parser holds `openTag` open so the element's children and close tag are handled as usual (the
14
+ * close dispatches `openTag`). When unset, {@link scan} consumes the whole element.
15
+ */
16
+ readonly openTag?: SaxesTag;
17
+ /**
18
+ * Consume the element whose `<` is at `start`. Returns the index just after what it consumed,
19
+ * {@link LeanSaxParser.NEED_MORE} when that runs past `end`, or
20
+ * {@link LeanSaxParser.NOT_HANDLED} (having changed nothing) to have it tokenized as usual.
21
+ */
22
+ scan(s: string, start: number, end: number): number;
23
+ }
24
+ export declare class LeanSaxParser {
25
+ static readonly NEED_MORE = -1;
26
+ static readonly NOT_HANDLED = -2;
27
+ /** Entity-decode text and normalize its line ends, as the `text` event delivers it. */
28
+ static decodeText(raw: string): string;
29
+ private _openTagHandler;
30
+ private _closeTagHandler;
31
+ private _textHandler;
32
+ private _cdataHandler;
33
+ private _errorHandler;
34
+ private _endHandler;
35
+ /** By the first character of the name; one scanner per first character. */
36
+ private _scanners;
37
+ /** Unconsumed input: a markup construct cut off by the end of the last chunk. */
38
+ private _carry;
39
+ /** Raw (undecoded) text since the last markup, possibly spanning chunks. */
40
+ private _text;
41
+ private _tags;
42
+ private _sawRoot;
43
+ private _closed;
44
+ on(name: LeanSaxEvent, handler: any): void;
45
+ setElementScanners(scanners: readonly ElementScanner[] | null): void;
46
+ fail(message: string): void;
47
+ write(chunk: string): this;
48
+ close(): this;
49
+ private _flushText;
50
+ /**
51
+ * Consume the markup starting at `lt`. Returns the index after it, or -1 when the markup runs
52
+ * past the end of `s` (the caller carries it into the next chunk).
53
+ */
54
+ private _markup;
55
+ private _openTag;
56
+ private _closeTag;
57
+ }
58
+ //# sourceMappingURL=LeanSaxParser.d.ts.map
@@ -1,4 +1,5 @@
1
1
  import { SaxesStartTag, SaxesTag, SaxesAttribute, SaxesAttributeNS, SaxesOptions } from './Saxes';
2
+ import { ElementScanner } from './LeanSaxParser';
2
3
  export declare namespace SaxParser {
3
4
  type StartTag = SaxesStartTag;
4
5
  type Tag = SaxesTag;
@@ -28,7 +29,16 @@ export declare namespace SaxParser {
28
29
  onText?: (text: string) => void;
29
30
  onError?: (error: any) => void;
30
31
  onEnd?: () => T;
32
+ /** Honored only by the lean parser (see {@link ParseOptions.lean}). */
33
+ elementScanners?: readonly ElementScanner[];
31
34
  }
32
- const parseStream: <T = any>(reader: ReadableStreamDefaultReader<string>, handler: EventHandler, options?: SaxesOptions) => Promise<T>;
35
+ interface ParseOptions extends SaxesOptions {
36
+ /**
37
+ * Use {@link LeanSaxParser}: non-validating and much faster, for large parts whose handler
38
+ * only needs tags, attributes and text. Implies `xmlns: false`.
39
+ */
40
+ lean?: boolean;
41
+ }
42
+ const parseStream: <T = any>(reader: ReadableStreamDefaultReader<string>, handler: EventHandler, options?: ParseOptions) => Promise<T>;
33
43
  }
34
44
  //# sourceMappingURL=SaxParser.d.ts.map
@@ -1,3 +1,4 @@
1
+ import { OnWarning, WarningOptions } from '../Warning';
1
2
  import { SaxParser } from './SaxParser';
2
3
  type ValueMutator = (value: any) => any;
3
4
  export declare const CopyMutators: {
@@ -23,7 +24,7 @@ export interface SAXExecutionContext<J = any> {
23
24
  * `closeTag`. `null` anywhere else.
24
25
  */
25
26
  getRawXml(): string | null;
26
- warn(message: string): void;
27
+ warn(message: string, options?: WarningOptions): void;
27
28
  }
28
29
  export interface SaxVisitor<J = any, P = any, C = any | void> {
29
30
  from: string;
@@ -67,7 +68,7 @@ export interface SaxVisitor<J = any, P = any, C = any | void> {
67
68
  export declare class SaxVisitHandler {
68
69
  protected _registeredVisitors: Map<string, SaxVisitor>;
69
70
  registerVisitor<J = any, P = any>(visitor: SaxVisitor<J, P>): void;
70
- createEventHandler(root: any, onEnd?: () => void, onWarning?: (message: string) => void): SaxParser.EventHandler;
71
+ createEventHandler(root: any, onEnd?: () => void, onWarning?: OnWarning): SaxParser.EventHandler;
71
72
  }
72
73
  export {};
73
74
  //# sourceMappingURL=SaxVisitor.d.ts.map
@@ -28,6 +28,15 @@ export interface ContentTypesDirectory {
28
28
  styles: string[];
29
29
  metadata: string[];
30
30
  people: string[];
31
+ /**
32
+ * Every `<Override>`, by part path (no leading `/`).
33
+ *
34
+ * @remarks
35
+ * The buckets above are the parts the reader looks for; this is for going the other way, asking
36
+ * what a part it already found is. A part carried through on the model has to carry its content
37
+ * type with it, and most of them are not derivable from a name.
38
+ */
39
+ overrides: Record<string, string>;
31
40
  /** First shared-strings part, or `''`. */
32
41
  sst: string;
33
42
  /** First styles part, or `''`. */
@@ -1,7 +1,13 @@
1
1
  import { Tuple, ISheet, ICell } from '@sheetxl/sdk';
2
2
  import { SaxParser } from '../sax';
3
- export declare const createWorksheetSaxVisitor: (sheet: ISheet.JSON, getRef: (relId: string, asBinary?: boolean) => any, // TODO - this should be a context like DOM.
4
- addSharedString: (str: string) => number, mapDxfs?: Map<number, any>, onEnd?: () => void, onWarning?: (message: string) => void, onProgress?: (amount: number, total?: number) => void, paramMap?: Map<string, any>) => SaxParser.EventHandler;
3
+ import { OnWarning } from '../Warning';
4
+ /**
5
+ * The `paramMap` key under which the reader hands the worksheet visitor the workbook's formula
6
+ * dialect (`XlsxFormulaDialect`), for condition formulas. Set before any sheet streams.
7
+ */
8
+ export declare const PARAM_FORMULA_DIALECT = "formulaDialect";
9
+ export declare const createWorksheetSaxVisitor: (sheet: ISheet.JSON, getRef: (relId: string, as?: "resource" | "legacyDrawing" | "part") => any, // TODO - this should be a context like DOM.
10
+ addSharedString: (str: string) => number, mapDxfs?: Map<number, any>, onEnd?: () => void, onWarning?: OnWarning, onProgress?: (amount: number, total?: number) => void, paramMap?: Map<string, any>) => SaxParser.EventHandler;
5
11
  export declare class RowAttributeType {
6
12
  static Collapsed: number;
7
13
  static CustomFormat: number;
@@ -19,7 +25,8 @@ export declare class RowAttributeType {
19
25
  /**
20
26
  * Special handler optimized for performance while reading sheet data.
21
27
  *
22
- * TODO - **PERFORMANCE**. Create a saxes flag that says to not build attribute object and event only (less objects and less lookups but would be per tag type)
28
+ * Under the lean parser, `<row>` start tags and `<c>` elements skip the generic tokenizer through
29
+ * the returned `elementScanners`.
23
30
  */
24
- export declare const createSheetDataSaxVisitor: (tupleBuilder: Tuple.IBuilder<ICell.JSON>, sheet: ISheet.JSON, delegate: SaxParser.EventHandler, onWarning: ((message: string) => void) | undefined, onProgress: ((amount: number, total?: number) => void) | undefined, stringHandler: SaxParser.EventHandler<number | undefined>, paramMap?: Map<string, any>) => SaxParser.EventHandler;
31
+ export declare const createSheetDataSaxVisitor: (tupleBuilder: Tuple.IBuilder<ICell.JSON>, sheet: ISheet.JSON, delegate: SaxParser.EventHandler, onWarning: OnWarning | undefined, onProgress: ((amount: number, total?: number) => void) | undefined, stringHandler: SaxParser.EventHandler<number | undefined>, paramMap?: Map<string, any>) => SaxParser.EventHandler;
25
32
  //# sourceMappingURL=WorksheetVisitor.d.ts.map
@@ -0,0 +1,75 @@
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, and writing them back beside the comment each belongs to.
4
+ *
5
+ * @remarks
6
+ * A note's box is a `<v:shape>` whose `<x:ClientData ObjectType="Note">` names its cell in
7
+ * `<x:Row>`/`<x:Column>` (0-based), and its corners in `<x:Anchor>` as four cell/offset pairs
8
+ * (left cell, left offset, top cell, top offset, right cell, right offset, bottom cell, bottom
9
+ * offset). Nothing else in the VML names a note, so the cell is the join to the comment.
10
+ *
11
+ * Excel writes the offsets in the authoring machine's pixels (PLAN-MODEL-HOMES §5), so on a move
12
+ * only the cell halves of the anchor are rewritten, by the same delta the note's cell moved; the
13
+ * offsets, the size and the absolute `style` are replayed as they were.
14
+ */
15
+ /** A note shape as read: its markup and the cell it was on. */
16
+ export interface NoteShape {
17
+ xml: string;
18
+ row: number;
19
+ col: number;
20
+ }
21
+ /**
22
+ * Splits the note shapes out of a VML part.
23
+ *
24
+ * @returns The part with the note shapes removed (`rest`), and the shapes with their cells.
25
+ * `rest` keeps the shapetype declarations, the control shapes and the closing root exactly as
26
+ * they were, so a part with no notes comes back byte for byte.
27
+ */
28
+ export declare function splitNoteShapes(xml: string): {
29
+ rest: string;
30
+ notes: NoteShape[];
31
+ };
32
+ /**
33
+ * Whether the part has any shape at all once its note boxes are taken out — a part that is only
34
+ * the root and the shapetype declarations has nothing left to say.
35
+ */
36
+ export declare function hasShapes(xml: string): boolean;
37
+ /**
38
+ * A note shape rewritten for the cell its comment is on now.
39
+ *
40
+ * @remarks
41
+ * `<x:Row>`/`<x:Column>` are the cell restated, and are written from it. The anchor's cell
42
+ * halves move by the delta from the cell the shape was read on, offsets untouched; a shape that
43
+ * declares neither `<x:MoveWithCells/>` nor `<x:SizeWithCells/>` is pinned and its anchor is
44
+ * left alone. The markup is returned as it was when nothing changed.
45
+ */
46
+ export declare function withNoteCell(shape: NoteShape, row: number, col: number): string;
47
+ /**
48
+ * The largest shape number the part uses, so a synthesized shape can take the next.
49
+ */
50
+ export declare function maxShapeId(xml: string): number;
51
+ /**
52
+ * A note box for a comment that has none: Excel's default — hidden until hovered, two columns
53
+ * wide and four rows tall, hung to the right of the cell — with the shape's own row and column.
54
+ *
55
+ * @remarks
56
+ * The geometry is the one Excel writes for a fresh note (and the one openpyxl writes, which
57
+ * Excel opens): an anchor of cell halves only, no absolute `style` beyond `visibility:hidden`
58
+ * and a nominal size, which Excel recomputes from the anchor.
59
+ */
60
+ export declare function synthesizeNoteShape(row: number, col: number, shapeId: number): string;
61
+ /** The shapetype every note box refers to, declared once per part. */
62
+ 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>";
63
+ /** An empty VML part, for a sheet whose notes have no drawing to be added to. */
64
+ 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>";
65
+ /**
66
+ * The part with the note shapes put back before the closing root.
67
+ *
68
+ * @remarks
69
+ * The note shapetype is declared once if any shape needs it and the part does not already
70
+ * declare it. A part that ends up with no shapes at all returns `null`: nothing to write.
71
+ */
72
+ export declare function assembleLegacyDrawing(rest: string | null, notes: string[]): string | null;
73
+ /** The shape's own number, if it declares one. */
74
+ export declare function shapeIdOf(xml: string): number | null;
75
+ //# 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";
@@ -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;