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

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 (55) hide show
  1. package/browser/esm/{Cv3R6fGatARKedSn.mjs → 9dwUocbOsJuAcmKn.mjs} +2514 -2058
  2. package/browser/esm/{CZ9I80og75SDRjv0.mjs → BIvDjK4Zl8bWRgl8.mjs} +2 -2
  3. package/browser/esm/{DatIA9fZbEPjW4bh.mjs → CcH5ITJFTMVWUJO9.mjs} +1810 -1294
  4. package/browser/esm/{yveeVJ6hKDI5KDEz.mjs → D8k22TSWPd_RHEpj.mjs} +1182 -1002
  5. package/browser/esm/{DICL6ecj9BdJv8aX.mjs → DKnOwucZq4z9_-r-.mjs} +4 -4
  6. package/browser/esm/{Bs0EzhdU8WgGfPzf.mjs → DO75RoAQTgMuVzXv.mjs} +2 -2
  7. package/browser/esm/{BiDqExNXiY7ykk8E.mjs → DVLJTjJCGqrJUa8c.mjs} +200 -199
  8. package/browser/esm/{CLWsOc6DO8l1G_LF.mjs → DeMZN_qj__PKo4Wh.mjs} +816 -764
  9. package/browser/esm/{CuAXx5i4uqTz-mMY.mjs → DsppUz-14Z7ti9i3.mjs} +1 -1
  10. package/browser/esm/{CzFYJPxmLyKgEKF0.mjs → aUBXbTh2r0u3x4Xo.mjs} +2 -2
  11. package/browser/esm/index.mjs +2 -2
  12. package/node/esm/{ipiyzn5Pfohw2afB.mjs → BmIIQODk4dBVIXA4.mjs} +1280 -1096
  13. package/node/esm/{CxlSbH7mmnEEsqmX.mjs → C-e5AO_4TnGywT-m.mjs} +1 -1
  14. package/node/esm/{DScqM1V4wPntNP6-.mjs → C78E45n6j2E8rruH.mjs} +2044 -1585
  15. package/node/esm/{Bpqm_PpGLpdjL47-.mjs → CDKm5s3JE_d99TJw.mjs} +242 -241
  16. package/node/esm/{CAJxmJdobUbzpUz5.mjs → DCaAOfuW-w_dx_qd.mjs} +2 -2
  17. package/node/esm/{fopiRR7OiVoEiF7B.mjs → DSgxL0sBZtWMydVl.mjs} +2 -2
  18. package/node/esm/DXusvwW73FUDSyvD.mjs +6367 -0
  19. package/node/esm/{B9Zn6H1RV07Ob377.mjs → DsyuWxk3bdGhJUQN.mjs} +512 -460
  20. package/node/esm/index.mjs +4 -4
  21. package/package.json +3 -3
  22. package/types/src/DataTableFormula.d.ts +36 -0
  23. package/types/src/chart/ChartSpaceXml.d.ts +2 -1
  24. package/types/src/chart/_chartCodecs.d.ts +2 -0
  25. package/types/src/reader/CellControls.d.ts +18 -0
  26. package/types/src/reader/LibreOfficeDataTable.d.ts +3 -2
  27. package/types/src/reader/domVisitors/ExternalLinkVisitor.d.ts +1 -1
  28. package/types/src/reader/domVisitors/FeaturePropertyBagVisitor.d.ts +27 -0
  29. package/types/src/reader/domVisitors/SheetStyleVisitor.d.ts +6 -0
  30. package/types/src/reader/domVisitors/index.d.ts +2 -4
  31. package/types/src/reader/saxVisitors/ContentTypesVisitor.d.ts +1 -0
  32. package/types/src/reader/saxVisitors/WorksheetVisitor.d.ts +14 -3
  33. package/types/src/richValue/ErrorRichValueHandler.d.ts +22 -0
  34. package/types/src/richValue/IRichValueHandler.d.ts +109 -0
  35. package/types/src/richValue/LocalImageRichValueHandler.d.ts +18 -0
  36. package/types/src/richValue/RichDataParts.d.ts +69 -0
  37. package/types/src/richValue/RichRecordWriter.d.ts +61 -0
  38. package/types/src/richValue/RichValueHandlers.d.ts +25 -0
  39. package/types/src/richValue/RichValueResolver.d.ts +54 -0
  40. package/types/src/richValue/WebImageRichValueHandler.d.ts +42 -0
  41. package/types/src/richValue/index.d.ts +7 -0
  42. package/types/src/writer/emitters/FeaturePropertyBagEmitter.d.ts +18 -0
  43. package/types/src/writer/emitters/RichValuePartsEmitters.d.ts +36 -0
  44. package/types/src/writer/emitters/RichValueRelEmitter.d.ts +12 -0
  45. package/types/src/writer/emitters/RichValueStructureEmitter.d.ts +4 -3
  46. package/types/src/writer/emitters/RichValueTypesEmitter.d.ts +3 -2
  47. package/types/src/writer/emitters/RichValueWebImageEmitter.d.ts +24 -0
  48. package/types/src/writer/emitters/SlicerEmitter.d.ts +5 -2
  49. package/types/src/writer/emitters/StylesEmitter.d.ts +2 -0
  50. package/types/src/writer/utils/CellControlComplements.d.ts +29 -0
  51. package/types/src/writer/utils/RichValueCollector.d.ts +81 -129
  52. package/types/src/writer/utils/SheetStyleLayout.d.ts +18 -5
  53. package/node/esm/DD-yXSBzvDYy0TX5.mjs +0 -5842
  54. package/types/src/reader/domVisitors/RichValueDataVisitor.d.ts +0 -7
  55. package/types/src/reader/domVisitors/RichValueStructureVisitor.d.ts +0 -6
@@ -0,0 +1,42 @@
1
+ import { IResource } from '@sheetxl/sdk';
2
+ import { IRichValueHandler, RichValueReadContext } from './IRichValueHandler';
3
+ /** The part listing the pictures `_webimage` rich values name, by position. */
4
+ export declare const WEB_IMAGES_PART = "/xl/richData/rdRichValueWebImage.xml";
5
+ /** One `<webImageSrd>`: where a picture came from, and the picture Excel kept. */
6
+ export interface WebImage {
7
+ /** The source URL (`address`), or `null` when the file names none. */
8
+ source: string | null;
9
+ /** The kept picture (`blip`), or `null`. */
10
+ bytes: ArrayBuffer | null;
11
+ }
12
+ /** A picture a `_webimage` written names: its source, and the resource holding its bytes. */
13
+ export interface WrittenWebImage {
14
+ source: string;
15
+ resource: IResource | null;
16
+ }
17
+ /**
18
+ * The pictures of rdRichValueWebImage.xml, in file order: a `_webimage`'s `WebImageIdentifier`
19
+ * indexes this list. Empty when the part is absent.
20
+ */
21
+ export declare const readWebImages: (ctx: RichValueReadContext) => WebImage[];
22
+ /**
23
+ * How a picture reached its cell, as a `_webimage`'s `CalcOrigin` says it: 1 for the result of an
24
+ * `IMAGE` call and 4 for a reference to one (`=A3`), as Excel writes them (probe-image-fetch,
25
+ * 2026-10-27). 2 for any other formula and 5 for a literal are [MS-XLSX]'s values as read, unprobed.
26
+ */
27
+ export declare const calcOriginOf: (formula: string | null) => number;
28
+ /**
29
+ * Excel's `_webimage` structure: a picture as a cell value (`IMAGE`), read as and written from an
30
+ * `image` value.
31
+ *
32
+ * @remarks
33
+ * The structure names its picture by position in rdRichValueWebImage.xml, which holds the source
34
+ * URL (`address`, an external hyperlink) and the picture Excel kept for it (`blip`, a media part).
35
+ * Reading adds each picture to the workbook as the resource its values hold; writing takes the
36
+ * bytes from the value's resource, else the workbook's fetch. Alt text, height and width have no
37
+ * key: Excel's file for them is unprobed.
38
+ *
39
+ * @internal
40
+ */
41
+ export declare const WebImageRichValueHandler: IRichValueHandler;
42
+ //# sourceMappingURL=WebImageRichValueHandler.d.ts.map
@@ -0,0 +1,7 @@
1
+ export * from './IRichValueHandler';
2
+ export * from './RichValueHandlers';
3
+ export { WEB_IMAGES_PART } from './WebImageRichValueHandler';
4
+ export * from './RichDataParts';
5
+ export * from './RichValueResolver';
6
+ export * from './RichRecordWriter';
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,18 @@
1
+ import { Emitter, EmitContext } from '../builder';
2
+ import { CellControlComplements } from '../utils/CellControlComplements';
3
+ /**
4
+ * Writes `xl/featurePropertyBag/featurePropertyBag.xml`: the controls the cell xfs' `xfComplement`
5
+ * indices stand for.
6
+ *
7
+ * @remarks
8
+ * The chain Excel writes for a checkbox (measured 2026-10-27, `checkbox.xlsx`), bags referenced by
9
+ * position: the control bag, an `XFControls` bag naming it as `CellControl`, an `XFComplement` bag
10
+ * naming that, and last one `XFComplements` bag whose `MappedFeaturePropertyBags` array lists the
11
+ * `XFComplement` bags. An xf's `xfComplement i` indexes that array, not the bags.
12
+ */
13
+ export declare class FeaturePropertyBagEmitter extends Emitter<CellControlComplements> {
14
+ constructor();
15
+ /** @inheritdoc IEmitter.emit */
16
+ emit(controlComplements: CellControlComplements, ctx: EmitContext): void;
17
+ }
18
+ //# sourceMappingURL=FeaturePropertyBagEmitter.d.ts.map
@@ -0,0 +1,36 @@
1
+ import { Emitter, EmitContext } from '../builder';
2
+ import { RichValueCollector } from '../utils/RichValueCollector';
3
+ /**
4
+ * Emits `rdarray.xml`: the arrays rich values hold (`_array`), each `<a r>` its items row major.
5
+ */
6
+ export declare class RichValueArrayEmitter extends Emitter<RichValueCollector> {
7
+ constructor();
8
+ /** @inheritdoc IEmitter.emit */
9
+ emit(rvCollector: RichValueCollector, ctx: EmitContext): Promise<void>;
10
+ }
11
+ /**
12
+ * Emits `rdsupportingpropertybagstructure.xml`: one `<s>` per supporting property bag structure.
13
+ */
14
+ export declare class RichValueBagStructureEmitter extends Emitter<RichValueCollector> {
15
+ constructor();
16
+ /** @inheritdoc IEmitter.emit */
17
+ emit(rvCollector: RichValueCollector, ctx: EmitContext): Promise<void>;
18
+ }
19
+ /**
20
+ * Emits `rdsupportingpropertybag.xml`: the bag arrays (`spbArrays`) and the bags (`spbData`).
21
+ */
22
+ export declare class RichValueBagEmitter extends Emitter<RichValueCollector> {
23
+ constructor();
24
+ /** @inheritdoc IEmitter.emit */
25
+ emit(rvCollector: RichValueCollector, ctx: EmitContext): Promise<void>;
26
+ }
27
+ /**
28
+ * Emits `richStyles.xml`: the styles a `_Format` bag names by 1-based index, each its number
29
+ * format and its card role (`IsTitleField`, `IsHeroField`).
30
+ */
31
+ export declare class RichValueStylesEmitter extends Emitter<RichValueCollector> {
32
+ constructor();
33
+ /** @inheritdoc IEmitter.emit */
34
+ emit(rvCollector: RichValueCollector, ctx: EmitContext): Promise<void>;
35
+ }
36
+ //# sourceMappingURL=RichValuePartsEmitters.d.ts.map
@@ -0,0 +1,12 @@
1
+ import { IResource } from '@sheetxl/sdk';
2
+ import { Emitter, EmitContext } from '../builder';
3
+ /**
4
+ * Emits `richValueRel.xml`: for each picture a `_localImage` value names, a relationship to its
5
+ * media part, in `_rvRel:LocalImageIdentifier` order.
6
+ */
7
+ export declare class RichValueRelEmitter extends Emitter<readonly IResource[]> {
8
+ constructor();
9
+ /** @inheritdoc IEmitter.emit */
10
+ emit(resources: readonly IResource[], ctx: EmitContext): Promise<void>;
11
+ }
12
+ //# sourceMappingURL=RichValueRelEmitter.d.ts.map
@@ -1,8 +1,9 @@
1
1
  import { Emitter, EmitContext } from '../builder';
2
- import { RichValueCollector, RichPrimitiveType } from '../utils/RichValueCollector';
2
+ import { RichPrimitiveType } from '../../richValue';
3
+ import { RichValueCollector } from '../utils/RichValueCollector';
3
4
  /**
4
- * Emits `rdrichvaluestructure.xml` — one `<s>` element per unique handler
5
- * type registered in the {@link RichValueCollector}.
5
+ * Emits `rdrichvaluestructure.xml` — one `<s>` element per structure written
6
+ * in the {@link RichValueCollector}.
6
7
  *
7
8
  * @remarks
8
9
  * Example output for a workbook that only has extended-error rich values:
@@ -1,10 +1,11 @@
1
1
  import { Emitter, EmitContext } from '../builder';
2
+ import { RichValueCollector } from '../utils/RichValueCollector';
2
3
  /**
3
4
  * Emits Rich Values
4
5
  */
5
- export declare class RichValueTypesEmitter extends Emitter<Map<any, string>> {
6
+ export declare class RichValueTypesEmitter extends Emitter<RichValueCollector | null> {
6
7
  constructor();
7
8
  /** @inheritdoc IEmitter.emit */
8
- emit(_params: any, ctx: EmitContext): Promise<void>;
9
+ emit(rvCollector: RichValueCollector | null, ctx: EmitContext): Promise<void>;
9
10
  }
10
11
  //# sourceMappingURL=RichValueTypesEmitter.d.ts.map
@@ -0,0 +1,24 @@
1
+ import { IWorkbook } from '@sheetxl/sdk';
2
+ import { WrittenWebImage } from '../../richValue/WebImageRichValueHandler';
3
+ import { Emitter, EmitContext } from '../builder';
4
+ /** What {@link RichValueWebImageEmitter} writes: the pictures, and the workbook to fetch any without bytes through. */
5
+ export interface RichValueWebImages {
6
+ /** The pictures, in `WebImageIdentifier` order. */
7
+ images: readonly WrittenWebImage[];
8
+ workbook: IWorkbook;
9
+ }
10
+ /**
11
+ * Emits `rdRichValueWebImage.xml`: for each picture a `_webimage` value names, its source URL
12
+ * (`address`, an external hyperlink) and the picture itself (`blip`, a media part), as Excel keeps
13
+ * an `IMAGE`'s picture in the file.
14
+ *
15
+ * @remarks
16
+ * The picture is the value's resource; a value with none is fetched through the workbook, and a
17
+ * source with no picture to give is written with its address alone.
18
+ */
19
+ export declare class RichValueWebImageEmitter extends Emitter<RichValueWebImages> {
20
+ constructor();
21
+ /** @inheritdoc IEmitter.emit */
22
+ emit(webImages: RichValueWebImages, ctx: EmitContext): Promise<void>;
23
+ }
24
+ //# sourceMappingURL=RichValueWebImageEmitter.d.ts.map
@@ -44,7 +44,7 @@ export declare class SlicerCacheEmitter extends Emitter<ISlicer> {
44
44
  }
45
45
  /**
46
46
  * Schedules a cache part for every table slicer of the workbook, in sheet order and then movable
47
- * order, and returns the relationship ids the workbook cites them by.
47
+ * order, and returns the relationship ids the workbook cites them by and the caches' names.
48
48
  *
49
49
  * @remarks
50
50
  * Called by `WorkbookEmitter` **after** the sheets have been written, since a cache names its table
@@ -52,7 +52,10 @@ export declare class SlicerCacheEmitter extends Emitter<ISlicer> {
52
52
  * scheduled is left out, with its slicer element still in the sheet's part; Excel repairs that
53
53
  * rather than refuse the file.
54
54
  */
55
- export declare const writeSlicerCaches: (ctx: EmitContext, workbook: IWorkbook) => string[];
55
+ export declare const writeSlicerCaches: (ctx: EmitContext, workbook: IWorkbook) => {
56
+ relIds: string[];
57
+ cacheNames: string[];
58
+ };
56
59
  /**
57
60
  * The sheet's `x15` slicer-list ext: schedules the sheet's slicer part and cites it. Written inside
58
61
  * the worksheet's `extLst`, after the conditional formats and data validations, where Excel puts it.
@@ -8,6 +8,8 @@ export declare class StylesEmitter extends Emitter<ModelHandle> {
8
8
  /** @inheritdoc IEmitter.emit */
9
9
  emit(handle: ModelHandle, ctx: EmitContext): Promise<void>;
10
10
  }
11
+ /** The namespace of the feature property bags and the xf complement. */
12
+ export declare const NS_FEATURE_PROPERTY_BAG = "http://schemas.microsoft.com/office/spreadsheetml/2022/featurepropertybag";
11
13
  /**
12
14
  * Writes ONE differential format.
13
15
  *
@@ -0,0 +1,29 @@
1
+ import { ICellControl } from '@sheetxl/sdk';
2
+ export declare const CELL_CONTROL_COMPLEMENTS_SHARED_STATE = "cellControlComplements";
3
+ /**
4
+ * The cell controls a workbook's xfs carry.
5
+ *
6
+ * @remarks
7
+ * The model keeps a cell control apart from the cell's style (`ICellControl`); xlsx keeps it on the
8
+ * cell's xf as an `xfComplement`. So the writer's xf is a pair, a style and a control, and the two
9
+ * meet only there: the style layout mints an xf per pair, and this records which complement each xf
10
+ * carries and which control each complement stands for (what the `featurePropertyBag` part lists).
11
+ */
12
+ export declare class CellControlComplements {
13
+ private _controls;
14
+ private _xfComplements;
15
+ /**
16
+ * The complement index for `control`, or `null` when xlsx cannot carry it.
17
+ *
18
+ * @remarks
19
+ * Only Excel's checkbox has a file form; another type is dropped (the caller warns).
20
+ */
21
+ getComplement(control: ICellControl.JSON): number | null;
22
+ /** The controls the complements stand for, by complement index. */
23
+ getControls(): readonly ICellControl.JSON[];
24
+ /** Records the complement each direct xf carries, by xf index, once the layout has minted them. */
25
+ setXfComplements(complements: readonly (number | undefined)[]): void;
26
+ /** The complement direct xf `xf` carries, or `null`. */
27
+ getXfComplement(xf: number): number | null;
28
+ }
29
+ //# sourceMappingURL=CellControlComplements.d.ts.map
@@ -1,4 +1,6 @@
1
- import { Scalar } from '@sheetxl/sdk';
1
+ import { IWorkbook, Scalar } from '@sheetxl/sdk';
2
+ import { EmitContext } from '../builder';
3
+ import { RichItemText, RichStructureKey, RichStyleDef, RichValueKeyFlags, RichValueSink, RichValueStructureDef } from '../../richValue';
2
4
  import { MetadataCollector } from './MetadataCollector';
3
5
  /**
4
6
  * Accumulates rich-value entries so that RichValueEmitter and
@@ -20,84 +22,33 @@ import { MetadataCollector } from './MetadataCollector';
20
22
  * ## XML output relationship
21
23
  *
22
24
  * ```
23
- * rdrichvaluestructure.xml – one <s> per unique handler type
25
+ * rdrichvaluestructure.xml – one <s> per structure written
24
26
  * rdrichvalue.xml – one <rv> per registered entry (s= → structure index)
25
27
  * metadata.xml futureMetadata XLRICHVALUE – one <bk> per unique rdrichvalue entry
26
28
  * metadata.xml valueMetadata – one <bk> per cell (vm= index)
27
29
  * ```
28
- */
29
- /**
30
- * OOXML primitive-value type codes used in `<k t="…">` attributes inside
31
- * `<rvStructures>`.
32
- *
33
- * "d" - Date/Time (ISO-8601 string)
34
- * "i" - Integer (32-bit signed)
35
- * "b" - Boolean
36
- * "e" - Error value
37
- * "s" - Inline string
38
- * "r" - Nested rich value
39
- * "a" - Array data (rdarray.xml)
40
- * "spb" - Supporting property bag
41
- */
42
- export type RichPrimitiveType = 'd' | 'i' | 'b' | 'e' | 's' | 'r' | 'a' | 'spb';
43
- /**
44
- * One property slot in a rich-value schema.
45
30
  *
46
- * - `name` – OOXML key name (`n=` attribute on `<k>`).
47
- * - `type` – OOXML primitive type (`t=` attribute on `<k>`).
48
- * - `defaultValue` – Serialized fallback used when the property is absent or
49
- * `undefined` on the raw value object. Defaults to `''`.
31
+ * What each value writes is its {@link IRichValueHandler}'s ({@link RichValueHandlers}).
50
32
  */
51
- export type RichValueProp = [name: string, type: RichPrimitiveType, defaultValue?: string];
52
- /**
53
- * Base class (and usable concrete class) for rich-value handler/schema types.
54
- *
55
- * Instantiate directly for pure-schema handlers:
56
- * ```ts
57
- * const MyHandler = new RichValueHandler('_myType', [
58
- * ['foo', 'i', '0'],
59
- * ['bar', 's', ''],
60
- * ]);
61
- * ```
62
- *
63
- * Subclass and override {@link getValues} for handlers that need custom
64
- * serialization logic.
65
- *
66
- * Pass instances to {@link RichValueCollector.register}.
67
- */
68
- export declare class RichValueHandler {
69
- /**
70
- * The OOXML structure type name (value of the `t=` attribute on `<s>`
71
- * inside `<rvStructures>`). E.g. `"_error"`.
72
- */
73
- readonly type: string;
74
- /**
75
- * Ordered property definitions written as `<k n="…" t="…"/>` inside the
76
- * matching `<s>` element in `rdrichvaluestructure.xml`.
77
- */
78
- readonly props: ReadonlyArray<RichValueProp>;
79
- constructor(type: string, props: ReadonlyArray<RichValueProp>);
80
- /**
81
- * Extracts the serializable string values for one `<rv>` entry in
82
- * `rdrichvalue.xml`. The array is parallel to {@link props}.
83
- *
84
- * The default implementation reads each property by name from `rawValue`
85
- * (treated as a `Record<string, unknown>`) and falls back to the prop's
86
- * `defaultValue` (or `''`) when the property is absent or `undefined`.
87
- *
88
- * Override in subclasses for custom serialization logic.
89
- *
90
- * @param rawValue The raw value that was passed to
91
- * {@link RichValueCollector.add} / `_register`.
92
- */
93
- getValues(rawValue: Record<string, unknown>): string[];
94
- }
95
33
  /** One registered rich-value entry. */
96
34
  export interface RichValueEntry {
97
- /** The handler (type descriptor / callback) for this entry. */
98
- handler: RichValueHandler;
99
- /** The raw value provided at registration time. */
100
- rawValue: any;
35
+ /** The structure the entry is written as. */
36
+ structure: RichValueStructureDef;
37
+ /** The `<v>`s, parallel to the structure's keys. */
38
+ values: readonly string[];
39
+ /** The `<fb>` cached number, for a formatted number. */
40
+ fb?: string;
41
+ }
42
+ /** One `<a>` of rdarray.xml. */
43
+ export interface RichArrayEntry {
44
+ rows: number;
45
+ columns: number;
46
+ items: readonly RichItemText[];
47
+ }
48
+ /** One `<spb>`: its bag structure's index and its `<v>`s. */
49
+ export interface RichBagEntry {
50
+ s: number;
51
+ values: readonly string[];
101
52
  }
102
53
  /**
103
54
  * Accumulates rich-value entries across all sheets.
@@ -107,12 +58,29 @@ export interface RichValueEntry {
107
58
  *
108
59
  * Stored in `sharedStates` under the key `"persistRichTypes"`.
109
60
  */
110
- export declare class RichValueCollector {
61
+ export declare class RichValueCollector implements RichValueSink {
111
62
  private readonly _metaCollector;
63
+ private readonly _workbook;
112
64
  private readonly _entries;
113
65
  private readonly _keyMap;
66
+ /** The writers started, by handler, in the order their structures are first written. */
67
+ private readonly _writers;
68
+ private readonly _structureIndex;
69
+ private readonly _structures;
70
+ private readonly _arrays;
71
+ private readonly _arrayKeys;
72
+ private readonly _bagStructures;
73
+ private readonly _bagStructureKeys;
74
+ private readonly _bags;
75
+ private readonly _bagKeys;
76
+ private readonly _bagArrays;
77
+ private readonly _bagArrayKeys;
78
+ private readonly _richStyles;
79
+ private readonly _richStyleKeys;
80
+ private readonly _keyFlags;
81
+ private readonly _records;
114
82
  private _onWarn;
115
- constructor(metaCollector: MetadataCollector, onWarn?: (message: string, value?: any) => void);
83
+ constructor(metaCollector: MetadataCollector, workbook: IWorkbook, onWarn?: (message: string, value?: any) => void);
116
84
  /**
117
85
  * Registers a cell value and returns the **1-based `vm=`** attribute value
118
86
  * to write on the `<c>` element — exactly like `persistStrings.add(text)`
@@ -122,37 +90,32 @@ export declare class RichValueCollector {
122
90
  * attrsCol.vm = '' + persistRichTypes.add(value);
123
91
  * ```
124
92
  *
125
- * Internally:
126
- * 1. Deduplicates the raw value → 0-based rdrichvalue.xml index (`rdRvIdx`)
127
- * 2. Deduplicates the futureMetadata XLRICHVALUE block (`rvFMBkIdx`)
128
- * 3. Appends a per-cell valueMetadata entry → 1-based `vm=`
129
- *
130
- * Dispatches on value type:
131
- * - `ScalarType.Error` with code > 7 → built-in `_error` handler
132
- * - Future: `ScalarType.RichData` → IRichType registry
93
+ * A value no handler writes is written as `#UNKNOWN!`.
133
94
  *
134
95
  * @param value The raw `Scalar` value from the cell iterator.
96
+ * @param formula The cell's formula text, or `null` for a literal: where a picture came from.
135
97
  * @returns 1-based `vm=` attribute value.
136
98
  */
137
- add(value: Scalar): number;
138
- /**
139
- * Registers (and deduplicates) a single `#UNKNOWN!` fallback rich-value entry.
140
- *
141
- * Used whenever a value cannot be serialized — produces valid OOXML and renders
142
- * as `#UNKNOWN!` in Excel rather than silently corrupting the `vm=` index.
143
- *
144
- * `#UNKNOWN!` is FormulaError code 12; OOXML `errorType` is `code - 1 = 11`.
145
- */
146
- private _registerFallback;
147
- /**
148
- * Low-level deduplicated entry registration.
149
- *
150
- * @param key Deduplication key (e.g. `"_error:9"`).
151
- * @param rawValue Forwarded to `handler.getValues()`.
152
- * @param handler Callback descriptor for this rich-value type.
153
- * @returns 0-based index into `rdrichvalue.xml`.
154
- */
155
- private _register;
99
+ add(value: Scalar, formula?: string | null): number;
100
+ /** {@inheritDoc RichValueSink.addHandled} */
101
+ addHandled(value: Scalar): number | null;
102
+ private _addHandled;
103
+ private _writerFor;
104
+ /** {@inheritDoc RichValueSink.structureFor} */
105
+ structureFor(t: string, keys: readonly RichStructureKey[]): RichValueStructureDef;
106
+ /** {@inheritDoc RichValueSink.addValue} */
107
+ addValue(structure: RichValueStructureDef, values: readonly string[], fb?: string): number;
108
+ /** {@inheritDoc RichValueSink.addArray} */
109
+ addArray(rows: number, columns: number, items: readonly RichItemText[]): number;
110
+ /** {@inheritDoc RichValueSink.addBag} */
111
+ addBag(keys: readonly RichStructureKey[], values: readonly string[]): number;
112
+ /** {@inheritDoc RichValueSink.addBagArray} */
113
+ addBagArray(items: readonly RichItemText[]): number;
114
+ /** {@inheritDoc RichValueSink.addRichStyle} */
115
+ addRichStyle(style: RichStyleDef): number;
116
+ /** {@inheritDoc RichValueSink.addKeyFlags} */
117
+ addKeyFlags(t: string, key: string, flags: readonly (readonly [name: string, value: string])[]): void;
118
+ private _intern;
156
119
  /** Number of registered (deduplicated) entries. */
157
120
  getCount(): number;
158
121
  /** Whether any entries have been registered. */
@@ -162,39 +125,28 @@ export declare class RichValueCollector {
162
125
  */
163
126
  getEntries(): readonly RichValueEntry[];
164
127
  /**
165
- * Returns the unique handler types in the order they are first encountered.
128
+ * The structures written, in the order they are first encountered.
166
129
  * Used by RichValueStructureEmitter to build `<rvStructures>`.
167
130
  */
168
- uniqueHandlers(): RichValueHandler[];
131
+ getStructures(): RichValueStructureDef[];
169
132
  /**
170
- * Returns the 0-based index of `handler` within the unique-handlers list
171
- * produced by {@link uniqueHandlers}. This is the `s=` attribute value on
133
+ * The 0-based index of `structure` within {@link getStructures}: the `s=` attribute value on
172
134
  * `<rv>` in `rdrichvalue.xml`.
173
135
  */
174
- handlerStructureIndex(handler: RichValueHandler): number;
136
+ getStructureIndex(structure: RichValueStructureDef): number;
137
+ /** The arrays written (rdarray.xml), in index order. */
138
+ getArrays(): readonly RichArrayEntry[];
139
+ /** The supporting property bag structures, bags and bag arrays written. */
140
+ getBags(): {
141
+ structures: readonly (readonly RichStructureKey[])[];
142
+ bags: readonly RichBagEntry[];
143
+ arrays: readonly (readonly RichItemText[])[];
144
+ };
145
+ /** The rich styles written, in index order (a bag names the first as 1). */
146
+ getRichStyles(): readonly RichStyleDef[];
147
+ /** The key flags each written structure declares in `rdRichValueTypes.xml`. */
148
+ getKeyFlags(): [structure: string, flags: readonly RichValueKeyFlags[]][];
149
+ /** Adds the parts the written structures need beyond the rich values. */
150
+ addParts(ctx: EmitContext): void;
175
151
  }
176
- /**
177
- // #PYTHON! contains a correlationId
178
- <s t="_error">
179
- <k n="correlationId" t="s"/>
180
- <k n="errorMessage" t="s"/>
181
- <k n="errorName" t="s"/>
182
- <k n="errorType" t="i"/>
183
- <k n="subType" t="i"/>
184
- </s>
185
-
186
-
187
- // #SPILL! contains row column offset
188
- <s t="_error">
189
- <k n="colOffset" t="i"/>
190
- <k n="errorType" t="i"/>
191
- <k n="rwOffset" t="i"/>
192
- <k n="subType" t="i"/>
193
- </s>
194
-
195
- // unknown has no subtype
196
- <s t="_error">
197
- <k n="errorType" t="i"/>
198
- </s>
199
- */
200
152
  //# sourceMappingURL=RichValueCollector.d.ts.map
@@ -1,5 +1,6 @@
1
1
  import { IRange, ICellStyle, ITypes, IWorkbook, IWorksheet } from '@sheetxl/sdk';
2
2
  import { XlsxHeader } from '../../XlsxHeader';
3
+ import { CellControlComplements } from './CellControlComplements';
3
4
  export { type XlsxHeader };
4
5
  /**
5
6
  * A worksheet as the sheet part writes it: the model's JSON with whole-row and whole-column styles
@@ -10,21 +11,33 @@ export interface XlsxWorksheetJSON extends Omit<IWorksheet.JSON, 'rows' | 'cols'
10
11
  rows?: IRange.JSONReference<XlsxHeader>[];
11
12
  }
12
13
  type StyledCells = [coords: IRange.Coords, styleId: number][];
13
- /** Looks style JSON up by direct style id, and mints ids for new JSON. */
14
+ /**
15
+ * Looks style JSON up by direct style id, and mints ids for new JSON.
16
+ *
17
+ * @remarks
18
+ * An id is an xf: a style plus the cell control complement it carries, if any (see
19
+ * `CellControlComplements`). The two stay apart; they meet only in the id.
20
+ */
14
21
  export interface StyleIdScope {
15
22
  getElementJSON(id: number): ICellStyle.JSON;
16
- getElementID(json: ICellStyle.JSON): number | null;
23
+ /** The control complement xf `id` carries, or `undefined`. */
24
+ getElementComplement?(id: number): number | undefined;
25
+ getElementID(json: ICellStyle.JSON, complement?: number): number | null;
17
26
  }
18
27
  /**
19
28
  * Direct style ids keyed by the style's JSON, the same way the SDK's persist scope keys them
20
- * (`JSONStableStringify`, Normal at 0), so a style keeps one xf however often it is minted.
29
+ * (`JSONStableStringify`, Normal at 0), so a style keeps one xf however often it is minted. A style
30
+ * under a cell control is a second xf, keyed by the pair.
21
31
  */
22
32
  export declare class StyleIds implements StyleIdScope {
23
33
  private _byKey;
24
34
  readonly list: ICellStyle.JSON[];
35
+ /** The control complement each xf carries, by id; parallel to {@link list}. */
36
+ readonly complements: (number | undefined)[];
25
37
  constructor(normal: ICellStyle.JSON | null | undefined);
26
38
  getElementJSON(id: number): ICellStyle.JSON;
27
- getElementID(json: ICellStyle.JSON | null | undefined): number;
39
+ getElementComplement(id: number): number | undefined;
40
+ getElementID(json: ICellStyle.JSON | null | undefined, complement?: number): number;
28
41
  }
29
42
  /**
30
43
  * Lays out every worksheet's styles the way xlsx stores them, re-minting the workbook's direct styles
@@ -37,7 +50,7 @@ export declare class StyleIds implements StyleIdScope {
37
50
  *
38
51
  * @returns The sheet part's JSON for each worksheet, keyed by the model's JSON for it.
39
52
  */
40
- export declare function layoutWorkbookStyles(json: IWorkbook.JSON, sheets: readonly (IWorksheet | null)[]): Map<IWorksheet.JSON, XlsxWorksheetJSON>;
53
+ export declare function layoutWorkbookStyles(json: IWorkbook.JSON, sheets: readonly (IWorksheet | null)[], complements?: CellControlComplements, warn?: (message: string, onceKey: string) => void): Map<IWorksheet.JSON, XlsxWorksheetJSON>;
41
54
  /**
42
55
  * Breaks a bordered range into pieces whose every cell draws the same edges, which is all a cell xf
43
56
  * can say.