@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
@@ -1,4 +1,4 @@
1
- import { IWorkbookIO } from '@sheetxl/sdk';
1
+ import { IWorkbook } from '@sheetxl/sdk';
2
2
  /**
3
3
  * The default upper bound, in decompressed bytes, on what a {@link SourcePackage} will retain.
4
4
  *
@@ -35,16 +35,33 @@ export interface SourcePackagePart {
35
35
  * @remarks
36
36
  * Not a residue map: this holds every non-streamed part from the source zip, decompressed. Which
37
37
  * of those a save actually copies through (vs. an emitter claiming the path, vs. a drop-bucket
38
- * rule) is decided at write time, not here.
38
+ * rule) is decided at write time, not here. The one thing it is told rather than holding is
39
+ * {@link isAbsorbed} — which parts the read put on the model, so the writer need not guess.
39
40
  */
40
41
  export declare class SourcePackage {
41
42
  private readonly _parts;
43
+ private readonly _absorbed;
42
44
  private readonly _totalBytes;
43
45
  private _structurallyChanged;
44
- constructor(parts: ReadonlyMap<string, SourcePackagePart>);
46
+ constructor(parts: ReadonlyMap<string, SourcePackagePart>, absorbed?: ReadonlySet<string> | null);
45
47
  getNames(): string[];
46
48
  has(name: string): boolean;
47
49
  getPart(name: string): SourcePackagePart | null;
50
+ /**
51
+ * Whether the reader took this part onto the model, so a save writes it from there rather than
52
+ * copying it through — see `DESIGN-PACKAGE-PASSTHROUGH.md` §4.
53
+ *
54
+ * @remarks
55
+ * Identity only: a name, never content. What each absorbed part *says* lives on the model that
56
+ * absorbed it (a chart's part on its movable, a sheet's VML on the sheet, a cache's definition on
57
+ * the workbook), which is the whole point of `PLAN-MODEL-HOMES.md` — this set exists so the
58
+ * passthrough can tell "the model owns this one" from "nothing modeled it" without a list of path
59
+ * patterns standing in for the answer.
60
+ *
61
+ * Independent of whether the element that cited the part still exists: deleting the chart deletes
62
+ * its part with it, and the source's copy should go too.
63
+ */
64
+ isAbsorbed(name: string): boolean;
48
65
  /** Sum of {@link SourcePackagePart.data}'s byte lengths across every retained part. */
49
66
  getTotalBytes(): number;
50
67
  /**
@@ -60,17 +77,19 @@ export declare class SourcePackage {
60
77
  hasStructuralChange(): boolean;
61
78
  markStructuralChange(): void;
62
79
  }
63
- /** The package retained for `origin`, or `null` if none was retained (or `origin` is unset). */
64
- export declare function getSourcePackage(origin: IWorkbookIO.Origin | null | undefined): SourcePackage | null;
80
+ /** The package retained for `workbook`, or `null` if none was retained. */
81
+ export declare function getSourcePackage(workbook: IWorkbook | null | undefined): SourcePackage | null;
65
82
  /**
66
- * Retain `sourcePackage` for `origin`, replacing anything previously retained for it.
83
+ * Retain `sourcePackage` for `workbook`, replacing anything previously retained for it.
67
84
  *
68
85
  * @remarks
69
- * Owned entirely by io-xlsx — the origin never learns this exists (no sdk change). Lifetime
70
- * follows the origin: stable across a save, fresh (and empty) for a copy or a new workbook, and
71
- * released via {@link releaseSourcePackage} on `IWorkbook.close()`.
86
+ * Owned entirely by io-xlsx — the workbook never learns this exists (no sdk change). Keyed by the
87
+ * WORKBOOK, not its origin: the parts belong to the model that was read, and pass through on every
88
+ * save of it wherever it is written — a Save As moves the workbook to a new origin, and the parts go
89
+ * with it. Fresh (and empty) for a copy or a new workbook; released via
90
+ * {@link releaseSourcePackage} on `IWorkbook.close()`.
72
91
  */
73
- export declare function setSourcePackage(origin: IWorkbookIO.Origin, sourcePackage: SourcePackage): void;
74
- /** Release whatever is retained for `origin`, if anything. Safe to call unconditionally. */
75
- export declare function releaseSourcePackage(origin: IWorkbookIO.Origin | null | undefined): void;
92
+ export declare function setSourcePackage(workbook: IWorkbook, sourcePackage: SourcePackage): void;
93
+ /** Release whatever is retained for `workbook`, if anything. Safe to call unconditionally. */
94
+ export declare function releaseSourcePackage(workbook: IWorkbook | null | undefined): void;
76
95
  //# sourceMappingURL=SourcePackage.d.ts.map
@@ -5,6 +5,23 @@ import { ReaderProfiler } from './reader/ReaderProfiler';
5
5
  * Options for exporting to XLSX file format.
6
6
  */
7
7
  export interface WriteXLSXOptions extends IWorkbookIO.WriteOptions {
8
+ /**
9
+ * Whether to write a macro-enabled workbook (`.xlsm`) rather than a plain one (`.xlsx`).
10
+ *
11
+ * @defaultValue false
12
+ *
13
+ * @remarks
14
+ * Set by the format registration, not by callers: `.xlsx` and `.xlsm` are two registered write
15
+ * formats sharing this one handler, which is how `DESIGN-IO.md` says a per-extension encoding
16
+ * decision must be expressed — a single format listing both extensions could not, because the
17
+ * handler is never told which of its extensions is being written.
18
+ *
19
+ * It decides **both halves together**, so the declaration can never disagree with the payload:
20
+ * the `xl/workbook.xml` content type, and whether a source package's `xl/vbaProject.bin` is
21
+ * carried through. Writing a macro workbook to `.xlsx` therefore drops the VBA project, which is
22
+ * what Excel's own *Save As* does.
23
+ */
24
+ macroEnabled?: boolean;
8
25
  /**
9
26
  * Callback invoked when a part is emitted.
10
27
  *
@@ -0,0 +1,16 @@
1
+ import { IWorkbook } from '@sheetxl/sdk';
2
+ /** The `paramMap` key under which the styles part leaves its `hidden="1"` cell xf indices. */
3
+ export declare const HIDDEN_XFS_PARAM = "hiddenXfs";
4
+ /**
5
+ * Turns xlsx's per-format `hidden` into the model's sheet `showFormulas` plus per-format grants.
6
+ *
7
+ * A formula shows when the sheet OR its format allows it; xlsx only has the format's `hidden`. So a
8
+ * sheet that uses any hidden format reads as `showFormulas: false` (an unprotected one keeping it as
9
+ * `sheet: true` protection), and every format it uses
10
+ * without `hidden="1"` is granted `showFormulas: true`. The formats are counted from the merged style
11
+ * references (cells, rows, columns, and xf 0 unless columns style everything), never per cell. xf 0 is Normal, so
12
+ * its grant goes on the Normal style, and the hidden formats say `false` outright rather than inherit
13
+ * it.
14
+ */
15
+ export declare const applyHiddenFormulas: (jsonWB: IWorkbook.JSON, hiddenXfs: ReadonlySet<number> | undefined) => void;
16
+ //# sourceMappingURL=HiddenFormulas.d.ts.map
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The sink a reader hands to everything it reads a part with.
3
+ *
4
+ * @remarks
5
+ * Load warnings belong to the host, which decides whether to show them — the CLI, for one, gates
6
+ * them on its log level. A warning written straight to the console has left that channel and
7
+ * cannot be silenced, so every transform a reader runs is given one of these.
8
+ *
9
+ * `context` locates the finding (the OPC path of the part, plus a sheet path where there is one).
10
+ * `onceKey` is {@link WarningOptions.onceKey}, carried from the emit site.
11
+ */
12
+ export type OnWarning = (message: string, context?: string, onceKey?: string) => void;
13
+ /** What an emit site may say about the warning it is raising, beyond its text. */
14
+ export interface WarningOptions {
15
+ /**
16
+ * Reports only the first warning carrying this key, for one read.
17
+ *
18
+ * @remarks
19
+ * Whether a warning means "this kind of thing, once" or "this specific thing" is known only
20
+ * where it is raised, so the key is the emit site's to give: a finding that names the shape it
21
+ * found is one per shape without a key, and one per file with one.
22
+ *
23
+ * Keys are stable dotted identifiers owned by this package, such as `xlsx.drawing.fixedShape`.
24
+ * Never derive one from the message text — rewording or localizing a message must not change
25
+ * what collapses. The first occurrence is the one reported, message and context both.
26
+ */
27
+ onceKey?: string;
28
+ }
29
+ //# sourceMappingURL=Warning.d.ts.map
@@ -22,7 +22,7 @@ export declare class DOMTransformer {
22
22
  * the `dxfs` table, so it arrives from the streaming reader with no index to look up. The
23
23
  * `processingDXFs` flag matters: a dxf's solid pattern fill has its colors inverted.
24
24
  */
25
- parseDxf(elem: Element, location?: string): IStyle.JSON;
25
+ parseDxf(elem: Element, location?: string, options?: TransformerOptions): IStyle.JSON;
26
26
  getVisitorParamsState(): Map<string, any>;
27
27
  transform(xmlRootDoc: Document, location: string, options?: TransformerOptions): any;
28
28
  protected _walkScoped(elemName: string, context: ExecutionContext, visited: VisitedRecord[], elemParent: Element, jsonParent: any, location: string, options: TransformerOptions): void;
@@ -1,4 +1,5 @@
1
- import { IComment } from '@sheetxl/sdk';
1
+ import { IPerson, IEmbeddedPart } from '@sheetxl/sdk';
2
+ import { WarningOptions } from '../Warning';
2
3
  import { RelationShipType, TransformerOptions } from './Types';
3
4
  export interface VisitorParamsContainer {
4
5
  getVisitorParamsState(): Map<string, any>;
@@ -22,18 +23,30 @@ export declare class ExecutionContext {
22
23
  private _onWarning?;
23
24
  private _addPerson?;
24
25
  private _serializeElement?;
26
+ private _readEmbeddedPart?;
25
27
  constructor(parent: ExecutionContext | null, sharedState: VisitorParamsContainer, currentPath: string, elemRoot: Element, jsonRoot: any, fileLocation?: string | null, options?: TransformerOptions);
26
28
  getRef(relId: string, asResource?: boolean): any;
29
+ /**
30
+ * The part this relationship names, and every part that part references, as one carried subtree.
31
+ *
32
+ * @remarks
33
+ * Not a flavor of {@link ExecutionContext.getRef}: that one interprets a relationship into
34
+ * whatever the reader models its target as, this one carries the target away unread so a writer
35
+ * can put it back. See {@link TransformerOptions.readEmbeddedPart}.
36
+ */
37
+ readEmbeddedPart(relId: string): IEmbeddedPart.JSON | null;
27
38
  getRelationships(): Map<string, RelationShipType>;
28
39
  getPath(): string;
29
40
  /** The OPC path of the file currently being read (e.g. "xl/drawings/drawing1.xml"). */
30
41
  getFileLocation(): string;
31
42
  getElemRoot(): Element;
32
43
  getJsonRoot(): any;
33
- warn(message: string): void;
44
+ warn(message: string, options?: WarningOptions): void;
45
+ /** Carries the originating part's path up to whichever context holds the sink. */
46
+ private _raiseWarning;
34
47
  /** Serializes a parsed DOM element back to an XML string, verbatim. Returns null if unavailable. */
35
48
  serializeElement(elem: Element): string | null;
36
- addPerson(person: string | Partial<IComment.PersonJSON>): IComment.PersonJSON | null;
49
+ addPerson(person: string | Partial<IPerson.JSON>): IPerson.JSON | null;
37
50
  getVisitorParamsState<T = any>(): Map<string, T>;
38
51
  /**
39
52
  * Evaluates a path expression against an XML element and returns matching elements.
@@ -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