reamkit 1.15.1 → 1.15.2

package/dist/esm/excel/slicer-parser.js

@@ -8,6 +8,11 @@ var parser = new XMLParser({
 	parseTagValue: false,
 	removeNSPrefix: true
 });
+/**
+* Parse `xl/slicers/slicerN.xml` into its {@link SlicerDef} panels (caption,
+* column count, style, cache name). A slicer missing a name or cache name is
+* skipped.
+*/
 function parseSlicerPart(data) {
 	const root = asObj(parser.parse(decoder.decode(data))["slicers"]);
 	if (!root) return [];
@@ -30,6 +35,11 @@ function parseSlicerPart(data) {
 	}
 	return out;
 }
+/**
+* Parse `xl/slicerCaches/slicerCacheN.xml` into a {@link SlicerCacheDef}, resolving
+* a native-table source (`extLst → ext → slicerCacheDefinition → tableSlicerCache`)
+* to its `tableId` + column. Returns undefined when the root or its name is missing.
+*/
 function parseSlicerCachePart(data) {
 	const root = asObj(parser.parse(decoder.decode(data))["slicerCacheDefinition"]);
 	if (!root) return void 0;

package/dist/esm/excel/styles-parser.d.ts

@@ -1,3 +1,11 @@
 import { XlsxStyles } from '../core/spreadsheet-model/index.js';
+/** The empty style table, returned for a workbook with no (or a malformed) `styles.xml`. */
 export declare const EMPTY_XLSX_STYLES: XlsxStyles;
+/**
+ * Parse `xl/styles.xml` (§18.8) into the {@link XlsxStyles} table the renderer
+ * consumes: custom number formats, fonts, fills, borders, the cell formats
+ * (`cellXfs` — each indexing font/fill/border/numFmt + optional alignment) and the
+ * differential formats (`dxfs`) conditional formatting applies. Returns
+ * {@link EMPTY_XLSX_STYLES} when the root is absent or malformed.
+ */
 export declare function parseXlsxStyles(data: Uint8Array): XlsxStyles;

package/dist/esm/excel/styles-parser.js

@@ -10,6 +10,7 @@ var parser = new XMLParser({
 	trimValues: false,
 	removeNSPrefix: true
 });
+/** The empty style table, returned for a workbook with no (or a malformed) `styles.xml`. */
 var EMPTY_XLSX_STYLES = {
 	numFmts: /* @__PURE__ */ new Map(),
 	fonts: [],
@@ -17,6 +18,13 @@ var EMPTY_XLSX_STYLES = {
 	borders: [],
 	cellXfs: []
 };
+/**
+* Parse `xl/styles.xml` (§18.8) into the {@link XlsxStyles} table the renderer
+* consumes: custom number formats, fonts, fills, borders, the cell formats
+* (`cellXfs` — each indexing font/fill/border/numFmt + optional alignment) and the
+* differential formats (`dxfs`) conditional formatting applies. Returns
+* {@link EMPTY_XLSX_STYLES} when the root is absent or malformed.
+*/
 function parseXlsxStyles(data) {
 	const xml = decoder.decode(data);
 	const root = asObject(parser.parse(xml)["styleSheet"]);

package/dist/esm/excel/table-parser.d.ts

@@ -1,12 +1,36 @@
 import { ExcelTable } from '../core/spreadsheet-model/index.js';
+/**
+ * §18.5.1.1 `<autoFilter><filterColumn colId><filters><filter val>` — the values
+ * a column's filter keeps visible. Used only for slicer selection (E-SHEET SV2);
+ * not part of the persisted {@link ExcelTable} (so the writer/roundtrip stay
+ * unchanged).
+ */
 export interface TableFilterColumn {
+    /** 0-based column offset within the table. */
     readonly colId: number;
+    /** The values the filter keeps visible. */
     readonly values: ReadonlyArray<string>;
 }
+/**
+ * The richer parse the reader needs for slicer resolution: the persisted
+ * {@link ExcelTable} plus the table's numeric id and any autofilter value filters.
+ */
 export interface ParsedTablePart {
     readonly table: ExcelTable;
+    /** The table's numeric `@id` (matched against a slicer cache's `tableId`). */
     readonly id?: number;
     readonly filters: ReadonlyArray<TableFilterColumn>;
 }
+/**
+ * Parse `xl/tables/tableN.xml` (§18.5.1.2) into the persisted {@link ExcelTable}
+ * (range, header-row count, autofilter presence, banded-style flags), or undefined
+ * when the root or its `ref` is missing. The slimmer of the two entry points;
+ * {@link parseTablePartFull} also returns the id + filters.
+ */
 export declare function parseTablePart(data: Uint8Array): ExcelTable | undefined;
+/**
+ * Parse a table part into the full {@link ParsedTablePart} — the {@link ExcelTable}
+ * plus the table's numeric id and any autofilter value filters (for slicer
+ * resolution). Returns undefined when the root or its `ref` is missing.
+ */
 export declare function parseTablePartFull(data: Uint8Array): ParsedTablePart | undefined;

package/dist/esm/excel/table-parser.js

@@ -9,6 +9,11 @@ var parser = new XMLParser({
 	parseTagValue: false,
 	removeNSPrefix: true
 });
+/**
+* Parse a table part into the full {@link ParsedTablePart} — the {@link ExcelTable}
+* plus the table's numeric id and any autofilter value filters (for slicer
+* resolution). Returns undefined when the root or its `ref` is missing.
+*/
 function parseTablePartFull(data) {
 	const t = asObj(parser.parse(decoder.decode(data))["table"]);
 	if (!t) return void 0;

package/dist/esm/excel/workbook-parser.d.ts

@@ -1,12 +1,29 @@
 import { DefinedName } from '../core/spreadsheet-model/index.js';
+/** §18.2.19 `<sheet name sheetId r:id>` — one worksheet reference in tab order. */
 export interface SheetReference {
+    /** The sheet (tab) display name. */
     readonly name: string;
+    /** The workbook-internal sheet id (`@sheetId`); `''` when absent. */
     readonly sheetId: string;
+    /** The relationship id (`r:id`) resolving to the sheet's worksheet part. */
     readonly relationshipId: string;
 }
+/** The parsed `workbook.xml`: the ordered sheet list, the date epoch and defined names. */
 export interface ParsedWorkbook {
+    /** The worksheet references in tab order. */
     readonly sheets: ReadonlyArray<SheetReference>;
+    /**
+     * ECMA-376 Part 1 §18.2.28 — `<workbookPr date1904="1"/>`. When true the
+     * serial-to-date conversion uses 1904-01-01 as day 0 instead of the
+     * standard 1899-12-30 epoch (legacy Mac Excel files).
+     */
     readonly date1904: boolean;
+    /** §18.2.5 workbook defined names (print areas/titles, named ranges). */
     readonly definedNames: ReadonlyArray<DefinedName>;
 }
+/**
+ * Parse `workbook.xml` into its ordered {@link SheetReference} list plus the date
+ * epoch and {@link ParsedWorkbook.definedNames}. A sheet entry missing a name or
+ * relationship id is skipped; a malformed root yields an empty workbook.
+ */
 export declare function parseWorkbook(data: Uint8Array): ParsedWorkbook;

package/dist/esm/excel/workbook-parser.js

@@ -10,6 +10,11 @@ var parser = new XMLParser({
 	trimValues: false,
 	removeNSPrefix: true
 });
+/**
+* Parse `workbook.xml` into its ordered {@link SheetReference} list plus the date
+* epoch and {@link ParsedWorkbook.definedNames}. A sheet entry missing a name or
+* relationship id is skipped; a malformed root yields an empty workbook.
+*/
 function parseWorkbook(data) {
 	const xml = decoder.decode(data);
 	const workbook = parser.parse(xml)["workbook"];

package/dist/esm/excel/worksheet-parser.d.ts

@@ -1,2 +1,11 @@
 import { ParsedWorksheet } from '../core/spreadsheet-model/index.js';
+/**
+ * Parse `worksheet.xml` (§18.3.1.99) into a {@link ParsedWorksheet}: a flat list
+ * of cells with absolute row/column addresses and their raw stored values, plus
+ * the per-sheet geometry and print model (columns, merges, row heights,
+ * pageMargins/pageSetup, breaks, frozen pane, conditional formats, data
+ * validations, hyperlinks, header/footer, form controls, OLE objects, sparklines
+ * and table parts). `r=` is optional on `<row>`/`<c>`; absent indices are inferred
+ * from document order. A malformed root or missing `sheetData` yields an empty grid.
+ */
 export declare function parseWorksheet(data: Uint8Array): ParsedWorksheet;

package/dist/esm/excel/worksheet-parser.js

@@ -12,6 +12,15 @@ var parser = new XMLParser({
 	trimValues: false,
 	removeNSPrefix: true
 });
+/**
+* Parse `worksheet.xml` (§18.3.1.99) into a {@link ParsedWorksheet}: a flat list
+* of cells with absolute row/column addresses and their raw stored values, plus
+* the per-sheet geometry and print model (columns, merges, row heights,
+* pageMargins/pageSetup, breaks, frozen pane, conditional formats, data
+* validations, hyperlinks, header/footer, form controls, OLE objects, sparklines
+* and table parts). `r=` is optional on `<row>`/`<c>`; absent indices are inferred
+* from document order. A malformed root or missing `sheetData` yields an empty grid.
+*/
 function parseWorksheet(data) {
 	const xml = decoder.decode(data);
 	const worksheet = parser.parse(xml)["worksheet"];

package/dist/esm/excel/xls/biff-chart.d.ts

@@ -4,5 +4,15 @@ interface Rec {
     readonly type: number;
     readonly data: Uint8Array;
 }
+/**
+ * Parse a BIFF chart substream (XLS-6) into a {@link Chart}. The series values
+ * are read straight from the host sheet's cells through each series' AI ranges
+ * (BIFF caches no plotted numbers, unlike OOXML).
+ *
+ * @param records       The chart substream's records (between its BOF…EOF).
+ * @param cells         The host sheet's cells (the value source for AI ranges).
+ * @param sharedStrings The workbook shared strings (for category / name text).
+ * @returns The chart, or `undefined` when there are no series to plot.
+ */
 export declare function parseBiffChart(records: ReadonlyArray<Rec>, cells: ReadonlyArray<WorksheetCell>, sharedStrings: ReadonlyArray<string>): Chart | undefined;
 export {};

package/dist/esm/excel/xls/biff-chart.js

@@ -8,6 +8,16 @@ var REC_SERIES = 4099;
 var REC_AI = 4177;
 var REC_SERIESTEXT = 4109;
 var COLS = 16384;
+/**
+* Parse a BIFF chart substream (XLS-6) into a {@link Chart}. The series values
+* are read straight from the host sheet's cells through each series' AI ranges
+* (BIFF caches no plotted numbers, unlike OOXML).
+*
+* @param records       The chart substream's records (between its BOF…EOF).
+* @param cells         The host sheet's cells (the value source for AI ranges).
+* @param sharedStrings The workbook shared strings (for category / name text).
+* @returns The chart, or `undefined` when there are no series to plot.
+*/
 function parseBiffChart(records, cells, sharedStrings) {
 	let type = "unknown";
 	let barDir;

package/dist/esm/excel/xls/biff-reader.d.ts

@@ -1,4 +1,31 @@
 import { SheetDoc } from '../../core/ir/sheet.js';
+/**
+ * Read a legacy `.xls` (BIFF8) workbook into a {@link SheetDoc} — the same IR
+ * tree the OOXML xlsx reader produces. Reads the workbook globals (sheet
+ * directory, shared strings, date system, styles, defined names, Escher BLIP
+ * store) and each worksheet substream's cells, styling and overlays.
+ *
+ * @param xls The `.xls` bytes (an OLE2/CFB container holding a `Workbook` stream).
+ * @returns The parsed spreadsheet IR tree.
+ * @throws Error on a non-OLE / non-BIFF8 input or a workbook with no worksheets
+ *   (the reader's sniff keeps malformed inputs away); a structurally odd record
+ *   is skipped, never fatal.
+ */
 export declare function readXlsToSheetDoc(xls: Uint8Array): SheetDoc;
+/**
+ * §2.5.198.5 RkNumber — decode a packed 30-bit number: bit 0 means ÷100, bit 1
+ * selects integer vs. the 30 high bits of an IEEE double. Exported for unit tests
+ * (the int / ×100 / IEEE paths).
+ */
 export declare function decodeRk(rk: number): number;
+/**
+ * §2.4.265 SST — read the shared-string table: `cstTotal`/`cstUnique` then
+ * `cstUnique` rich strings, via a continuation-aware reader (a string can split
+ * across a CONTINUE boundary, and the byte after the boundary is a fresh
+ * `fHighByte` flag for the rest). Exported for unit tests of the continuation
+ * handling.
+ *
+ * @param blocks The SST record's data followed by each CONTINUE record's data.
+ * @returns The unique shared strings, in index order.
+ */
 export declare function readSst(blocks: ReadonlyArray<Uint8Array>): Array<string>;

package/dist/esm/excel/xls/biff-reader.js

@@ -57,6 +57,18 @@ var MAX_SHEETS = 4096;
 var MAX_CELLS = 1 << 22;
 var MAX_STRINGS = 1 << 21;
 var MAX_ROW_HEIGHTS = 1 << 20;
+/**
+* Read a legacy `.xls` (BIFF8) workbook into a {@link SheetDoc} — the same IR
+* tree the OOXML xlsx reader produces. Reads the workbook globals (sheet
+* directory, shared strings, date system, styles, defined names, Escher BLIP
+* store) and each worksheet substream's cells, styling and overlays.
+*
+* @param xls The `.xls` bytes (an OLE2/CFB container holding a `Workbook` stream).
+* @returns The parsed spreadsheet IR tree.
+* @throws Error on a non-OLE / non-BIFF8 input or a workbook with no worksheets
+*   (the reader's sniff keeps malformed inputs away); a structurally odd record
+*   is skipped, never fatal.
+*/
 function readXlsToSheetDoc(xls) {
 	const cfb = openCfb(xls);
 	const wb = cfb.readStream("Workbook") ?? cfb.readStream("Book");
@@ -1282,6 +1294,11 @@ function formulaCell(d, next) {
 	}
 	return numCell(row, col, style, String(readF64(d, 6)));
 }
+/**
+* §2.5.198.5 RkNumber — decode a packed 30-bit number: bit 0 means ÷100, bit 1
+* selects integer vs. the 30 high bits of an IEEE double. Exported for unit tests
+* (the int / ×100 / IEEE paths).
+*/
 function decodeRk(rk) {
 	const div100 = (rk & 1) !== 0;
 	let value;
@@ -1330,6 +1347,16 @@ function decodeChars(d, off, cch, highByte) {
 	else for (let i = 0; i < cch && off + i < d.length; i++) s += String.fromCharCode(d[off + i]);
 	return s;
 }
+/**
+* §2.4.265 SST — read the shared-string table: `cstTotal`/`cstUnique` then
+* `cstUnique` rich strings, via a continuation-aware reader (a string can split
+* across a CONTINUE boundary, and the byte after the boundary is a fresh
+* `fHighByte` flag for the rest). Exported for unit tests of the continuation
+* handling.
+*
+* @param blocks The SST record's data followed by each CONTINUE record's data.
+* @returns The unique shared strings, in index order.
+*/
 function readSst(blocks) {
 	const r = new SstReader(blocks);
 	r.u32();
@@ -1338,33 +1365,45 @@ function readSst(blocks) {
 	for (let i = 0; i < cstUnique && !r.atEnd(); i++) out.push(r.readString());
 	return out;
 }
+/**
+* A cursor over the SST's record blocks. Header/flag reads stay within a block
+* (the spec never splits them); only the character array crosses boundaries, and
+* each crossing re-reads the `fHighByte` flag.
+*/
 var SstReader = class {
 	bi = 0;
 	off = 0;
+	/** @param blocks The SST record's data followed by each CONTINUE record's data. */
 	constructor(blocks) {
 		this.blocks = blocks;
 	}
+	/** Whether the cursor has consumed every block. */
 	atEnd() {
 		this.settle();
 		return this.bi >= this.blocks.length;
 	}
+	/** Advance off the end of exhausted blocks (a "skip" crossing — no flag byte). */
 	settle() {
 		while (this.bi < this.blocks.length && this.off >= this.blocks[this.bi].length) {
 			this.bi++;
 			this.off = 0;
 		}
 	}
+	/** Read one byte, advancing across exhausted blocks; 0 past the end. */
 	byte() {
 		this.settle();
 		if (this.bi >= this.blocks.length) return 0;
 		return this.blocks[this.bi][this.off++];
 	}
+	/** Read a little-endian unsigned 16-bit integer. */
 	u16() {
 		return this.byte() | this.byte() << 8;
 	}
+	/** Read a little-endian unsigned 32-bit integer. */
 	u32() {
 		return (this.u16() | this.u16() << 16) >>> 0;
 	}
+	/** Skip `n` bytes (used for the rich-run + phonetic tails, which carry no flags). */
 	skip(n) {
 		let left = n;
 		while (left > 0) {
@@ -1375,6 +1414,11 @@ var SstReader = class {
 			left -= take;
 		}
 	}
+	/**
+	* Read one XLUnicodeRichExtendedString: a 16-bit char count, a flags byte, the
+	* optional rich-run / phonetic sizes, the (possibly continuation-split)
+	* characters, then the skipped rich-run + phonetic tails.
+	*/
 	readString() {
 		const cch = this.u16();
 		const flags = this.byte();

package/dist/esm/excel/xls/biff-styles.d.ts

@@ -3,6 +3,26 @@ interface BiffRec {
     readonly type: number;
     readonly data: Uint8Array;
 }
+/**
+ * Build a palette-index → `"FFRRGGBB"` (8-hex ARGB, like the xlsx `rgb` attr)
+ * resolver from the default 56-colour palette plus any `PALETTE` override.
+ * `0x7FFF` / 64 / 65 are automatic or system colours → `undefined` (the renderer
+ * default). Exported so the conditional-format reader (XLS-13) resolves its dxf
+ * colours the same way.
+ *
+ * @param records The workbook-globals records (scanned for a `PALETTE` override).
+ * @returns A function mapping a colour index (icv) to its hex, or `undefined`.
+ */
 export declare function buildBiffPalette(records: ReadonlyArray<BiffRec>): (icv: number) => string | undefined;
+/**
+ * Read a `.xls` workbook globals' FONT / FORMAT / PALETTE / XF records (XLS-4)
+ * into the shared `XlsxStyles` model the OOXML path uses. BIFF packs each XF's
+ * fill and border inline and stores colours as palette indices; these are
+ * resolved through {@link buildBiffPalette} and de-duplicated into the model's
+ * shared fill/border arrays.
+ *
+ * @param records The workbook-globals record stream.
+ * @returns The style table (numFmts, fonts, fills, borders, cellXfs).
+ */
 export declare function parseBiffStyles(records: ReadonlyArray<BiffRec>): XlsxStyles;
 export {};

package/dist/esm/excel/xls/biff-styles.js

@@ -115,6 +115,16 @@ var PALETTE56 = [
 	"333399",
 	"333333"
 ];
+/**
+* Build a palette-index → `"FFRRGGBB"` (8-hex ARGB, like the xlsx `rgb` attr)
+* resolver from the default 56-colour palette plus any `PALETTE` override.
+* `0x7FFF` / 64 / 65 are automatic or system colours → `undefined` (the renderer
+* default). Exported so the conditional-format reader (XLS-13) resolves its dxf
+* colours the same way.
+*
+* @param records The workbook-globals records (scanned for a `PALETTE` override).
+* @returns A function mapping a colour index (icv) to its hex, or `undefined`.
+*/
 function buildBiffPalette(records) {
 	const palette = [...PALETTE56.slice(0, 8), ...PALETTE56];
 	for (const rec of records) if (rec.type === REC_PALETTE) applyPalette(rec.data, palette);
@@ -124,6 +134,16 @@ function buildBiffPalette(records) {
 		return rgb ? `FF${rgb}` : void 0;
 	};
 }
+/**
+* Read a `.xls` workbook globals' FONT / FORMAT / PALETTE / XF records (XLS-4)
+* into the shared `XlsxStyles` model the OOXML path uses. BIFF packs each XF's
+* fill and border inline and stores colours as palette indices; these are
+* resolved through {@link buildBiffPalette} and de-duplicated into the model's
+* shared fill/border arrays.
+*
+* @param records The workbook-globals record stream.
+* @returns The style table (numFmts, fonts, fills, borders, cellXfs).
+*/
 function parseBiffStyles(records) {
 	const color = buildBiffPalette(records);
 	const fonts = [];

package/dist/esm/excel/xls/escher.d.ts

@@ -1,7 +1,10 @@
+/** A picture shape: the BLIP store index it references plus its cell anchor. */
 export interface EscherPicture {
+    /** 1-based index into the BLIP store (the OPT `pib` property). */
     readonly blipIndex: number;
     readonly anchor?: EscherAnchor;
 }
+/** A from/to two-cell anchor (each cell index a u16, each offset 1/1024 of the cell). */
 export interface EscherAnchor {
     readonly col1: number;
     readonly row1: number;
@@ -12,13 +15,37 @@ export interface EscherAnchor {
     readonly dx2: number;
     readonly dy2: number;
 }
+/**
+ * Read the workbook-globals MSODrawingGroup's BLIP store: one entry per BSE (so a
+ * `pib` index lines up), holding the extracted image bytes — or `undefined` for
+ * an entry we cannot read (a metafile blip, an empty slot), which keeps the
+ * indices aligned.
+ *
+ * @param msoDrawingGroup The concatenated MSODrawingGroup record bytes.
+ * @returns The image pool, indexed so `pib − 1` selects an entry.
+ */
 export declare function parseBlipStore(msoDrawingGroup: Uint8Array): Array<Uint8Array | undefined>;
+/**
+ * The picture shapes in a sheet's MSODrawing: every SpContainer that carries a
+ * `pib` (a picture-fill reference into the BLIP store) with its cell anchor.
+ */
 export declare function parseSheetPictures(msoDrawing: Uint8Array): Array<EscherPicture>;
+/**
+ * A non-picture drawing shape: its preset type (MSOSPT), cell anchor, fill/line
+ * colours (when literal RGB) and whether it carries a text box.
+ */
 export interface EscherShape {
+    /** The MSOSPT preset shape type (the Sp record's instance). */
     readonly shapeType: number;
+    /** Whether the shape carries a client text box. */
     readonly hasText: boolean;
     readonly anchor?: EscherAnchor;
     readonly fillColorHex?: string;
     readonly lineColorHex?: string;
 }
+/**
+ * The non-picture shapes (autoshapes, text boxes) in a sheet's MSODrawing — every
+ * SpContainer that is NOT a picture (no `pib`). Pictures are handled separately
+ * by {@link parseSheetPictures}.
+ */
 export declare function parseSheetShapes(msoDrawing: Uint8Array): Array<EscherShape>;

package/dist/esm/excel/xls/escher.js

@@ -24,6 +24,15 @@ function* records(d) {
 		off = end;
 	}
 }
+/**
+* Read the workbook-globals MSODrawingGroup's BLIP store: one entry per BSE (so a
+* `pib` index lines up), holding the extracted image bytes — or `undefined` for
+* an entry we cannot read (a metafile blip, an empty slot), which keeps the
+* indices aligned.
+*
+* @param msoDrawingGroup The concatenated MSODrawingGroup record bytes.
+* @returns The image pool, indexed so `pib − 1` selects an entry.
+*/
 function parseBlipStore(msoDrawingGroup) {
 	const store = findContainer(msoDrawingGroup, FBT_BSTORE_CONTAINER, 0);
 	if (!store) return [];
@@ -41,6 +50,10 @@ function findContainer(d, type, depth) {
 		}
 	}
 }
+/**
+* The picture shapes in a sheet's MSODrawing: every SpContainer that carries a
+* `pib` (a picture-fill reference into the BLIP store) with its cell anchor.
+*/
 function parseSheetPictures(msoDrawing) {
 	const out = [];
 	collectPictures(msoDrawing, out, 0);
@@ -63,6 +76,11 @@ var FBT_SP = 61450;
 var FBT_CLIENT_TEXTBOX = 61453;
 var PROP_FILL_COLOR = 385;
 var PROP_LINE_COLOR = 448;
+/**
+* The non-picture shapes (autoshapes, text boxes) in a sheet's MSODrawing — every
+* SpContainer that is NOT a picture (no `pib`). Pictures are handled separately
+* by {@link parseSheetPictures}.
+*/
 function parseSheetShapes(msoDrawing) {
 	const out = [];
 	collectShapes(msoDrawing, out, 0);

package/dist/esm/excel/xls/xls-reader.d.ts

@@ -1,3 +1,9 @@
 import { DocumentReader } from '../../core/ir/adapters.js';
 import { SheetDoc } from '../../core/ir/sheet.js';
+/**
+ * The legacy `.xls` {@link DocumentReader} (XLS-3): sniffs a BIFF8 OLE2/CFB
+ * workbook and reads it into the same {@link SheetDoc} the OOXML xlsx reader
+ * produces, so the whole render pipeline works on a 1997–2003 `.xls`. Reports a
+ * single degraded {@link Loss} for the unread Excel-tables / autofilter feature.
+ */
 export declare const xlsReader: DocumentReader<SheetDoc>;

package/dist/esm/excel/xls/xls-reader.js

@@ -16,6 +16,12 @@ var XLS_LOSSES = [{
 	feature: FEATURES.cellFormatting,
 	detail: "legacy .xls Excel tables / autofilter are not read; the sheet’s cell data, styling, images, charts, drawing shapes, conditional formatting, comments, hyperlinks, data validation, defined names, the page-setup print model, frozen panes and custom row heights are"
 }];
+/**
+* The legacy `.xls` {@link DocumentReader} (XLS-3): sniffs a BIFF8 OLE2/CFB
+* workbook and reads it into the same {@link SheetDoc} the OOXML xlsx reader
+* produces, so the whole render pipeline works on a 1997–2003 `.xls`. Reports a
+* single degraded {@link Loss} for the unread Excel-tables / autofilter feature.
+*/
 var xlsReader = {
 	id: "xls",
 	produces: "sheet",

package/dist/esm/excel/xlsx-reader.d.ts

@@ -2,6 +2,32 @@ import { DocumentReader, ReadResult } from '../core/ir/adapters.js';
 import { FlowDoc } from '../core/ir/flow.js';
 import { SheetDoc } from '../core/ir/sheet.js';
 import { ProjectSheetOptions } from './sheet-to-flow.js';
+/**
+ * Read a `.xlsx` and project it to a {@link FlowDoc} in one step:
+ * {@link readXlsxToSheetDoc} then {@link projectSheetDoc}. The xlsx reader
+ * records no read-time losses.
+ *
+ * @param xlsx    The `.xlsx` (OPC ZIP) bytes.
+ * @param options Projection knobs (the W9 reference date).
+ * @returns The flow document plus an (empty) loss list.
+ */
 export declare function readXlsx(xlsx: Uint8Array, options?: ProjectSheetOptions): ReadResult<FlowDoc>;
+/**
+ * Read a `.xlsx` into the {@link SheetDoc} SpreadsheetML IR node. Everything that
+ * needs the OPC package — workbook/worksheet/styles/shared-string parsing, chart
+ * and drawing resolution, tables, pivots, slicers, hyperlinks, comments and
+ * controls — happens here; the SheetDoc → FlowDoc projection (sheet-to-flow) is
+ * then a pure transform.
+ *
+ * @param xlsx The `.xlsx` (OPC ZIP) bytes.
+ * @returns The parsed spreadsheet IR tree.
+ * @throws Error when `xl/workbook.xml` is missing or the workbook has no sheets.
+ */
 export declare function readXlsxToSheetDoc(xlsx: Uint8Array): SheetDoc;
+/**
+ * The OOXML `.xlsx` {@link DocumentReader}: sniffs the OPC ZIP for
+ * `xl/workbook.xml` and reads it into a {@link SheetDoc}. The reader's native
+ * tree is the SheetDoc; the facade/Ream project it to a {@link FlowDoc} for
+ * rendering (E-SHEET SB1).
+ */
 export declare const xlsxReader: DocumentReader<SheetDoc>;

package/dist/esm/excel/xlsx-reader.js

@@ -34,12 +34,32 @@ var SLICER_CACHE_REL_TAIL = "/slicerCache";
 var THREADED_COMMENTS_REL_TAIL = "/threadedComment";
 var PERSON_REL_TAIL = "/person";
 var MAX_SLICER_ITEMS = 256;
+/**
+* Read a `.xlsx` and project it to a {@link FlowDoc} in one step:
+* {@link readXlsxToSheetDoc} then {@link projectSheetDoc}. The xlsx reader
+* records no read-time losses.
+*
+* @param xlsx    The `.xlsx` (OPC ZIP) bytes.
+* @param options Projection knobs (the W9 reference date).
+* @returns The flow document plus an (empty) loss list.
+*/
 function readXlsx(xlsx, options = {}) {
 	return {
 		doc: projectSheetDoc(readXlsxToSheetDoc(xlsx), options),
 		losses: []
 	};
 }
+/**
+* Read a `.xlsx` into the {@link SheetDoc} SpreadsheetML IR node. Everything that
+* needs the OPC package — workbook/worksheet/styles/shared-string parsing, chart
+* and drawing resolution, tables, pivots, slicers, hyperlinks, comments and
+* controls — happens here; the SheetDoc → FlowDoc projection (sheet-to-flow) is
+* then a pure transform.
+*
+* @param xlsx The `.xlsx` (OPC ZIP) bytes.
+* @returns The parsed spreadsheet IR tree.
+* @throws Error when `xl/workbook.xml` is missing or the workbook has no sheets.
+*/
 function readXlsxToSheetDoc(xlsx) {
 	const pkg = OpcPackage.open(xlsx);
 	const workbookData = pkg.getPart(WORKBOOK_PART);
@@ -384,6 +404,12 @@ function lighten(hex, amount) {
 	const hx = (c) => c.toString(16).padStart(2, "0").toUpperCase();
 	return `${hx(ch(16))}${hx(ch(8))}${hx(ch(0))}`;
 }
+/**
+* The OOXML `.xlsx` {@link DocumentReader}: sniffs the OPC ZIP for
+* `xl/workbook.xml` and reads it into a {@link SheetDoc}. The reader's native
+* tree is the SheetDoc; the facade/Ream project it to a {@link FlowDoc} for
+* rendering (E-SHEET SB1).
+*/
 var xlsxReader = {
 	id: "xlsx",
 	produces: "sheet",

package/dist/esm/excel/xlsx-to-pdf.d.ts

@@ -1,13 +1,40 @@
 import { FontBytesByVariant } from '../core/font/index.js';
 import { FetchLike } from '../core/fonts/index.js';
 import { SignatureOptions, StyledRenderOptions } from '../pdf/index.js';
+/**
+ * Options for the xlsx → PDF convenience converters. Extends the low-level
+ * {@link StyledRenderOptions} (minus the font `registry` and `styles`, which the
+ * converter builds itself) with font acquisition and source-touching conveniences.
+ */
 export interface ConvertXlsxOptions extends Omit<StyledRenderOptions, 'registry' | 'styles'> {
+    /** Shorthand for supplying a single regular-variant font as raw bytes. */
     readonly fontBytes?: Uint8Array;
+    /** Explicit font bytes per variant (regular/bold/italic/bold-italic). */
     readonly fonts?: FontBytesByVariant;
+    /**
+     * Force a substitute font family for the auto-download path. Ignored when
+     * `fonts`/`fontBytes` are supplied.
+     */
     readonly fontFamily?: string;
+    /** Injectable `fetch` for the auto-download path (defaults to the global `fetch`). */
     readonly fontFetch?: FetchLike;
+    /**
+     * For PDF/A-3 only: embed the input `.xlsx` as an associated source file
+     * (`/AFRelationship /Source`). Ignored for other profiles.
+     */
     readonly embedSource?: boolean;
+    /**
+     * E-SHEET W9 — the reference date for conditional-format `timePeriod` rules and
+     * `TODAY()`/`NOW()` in `expression` rules. An explicit input (never the wall
+     * clock), so output stays deterministic; omitted ⇒ those clock-relative rules
+     * no-op.
+     */
     readonly now?: Date;
+    /**
+     * Digitally sign the output (ISO 32000 §12.8). Requires the async
+     * {@link convertXlsxToPdf} (signing uses WebCrypto). Ignored by the sync
+     * converter.
+     */
     readonly signature?: SignatureOptions;
 }
 /**