reamkit 1.15.1 → 1.15.2

package/dist/esm/excel/formula/value.js

@@ -1,13 +1,17 @@
 //#region src/excel/formula/value.ts
+/** The blank scalar (an empty / absent cell). */
 var BLANK = { t: "blank" };
+/** The logical TRUE scalar. */
 var TRUE = {
 	t: "bool",
 	v: true
 };
+/** The logical FALSE scalar. */
 var FALSE = {
 	t: "bool",
 	v: false
 };
+/** Wrap a number as a scalar; a non-finite result (overflow, 0/0) becomes `#NUM!`. */
 function num(v) {
 	return Number.isFinite(v) ? {
 		t: "num",
@@ -17,24 +21,34 @@ function num(v) {
 		v: "#NUM!"
 	};
 }
+/** Wrap a string as a text scalar. */
 function str(v) {
 	return {
 		t: "str",
 		v
 	};
 }
+/** The {@link TRUE} / {@link FALSE} scalar for a boolean. */
 function bool(v) {
 	return v ? TRUE : FALSE;
 }
+/** Wrap an error code as an error scalar. */
 function err(v) {
 	return {
 		t: "err",
 		v
 	};
 }
+/** Type guard: is the value an error scalar? */
 function isErr(v) {
 	return v.t === "err";
 }
+/**
+* Collapse a reference to a scalar: a 1×1 rect yields the cell's value (a blank cell
+* → blank); any larger rect in a scalar context is `#VALUE!` (we do not implement
+* implicit intersection). An array constant collapses to its top-left element;
+* non-refs pass through unchanged.
+*/
 function deref(v, ctx) {
 	if (v.t === "arr") return v.rows[0]?.[0] ?? BLANK;
 	if (v.t !== "ref") return v;
@@ -42,16 +56,27 @@ function deref(v, ctx) {
 	if (r0 === r1 && c0 === c1) return refGet(v.sheet, ctx, r0, c0);
 	return err("#VALUE!");
 }
+/** Visit every scalar element of an array constant, row by row. */
 function arrEach(rows, visit) {
 	for (const row of rows) for (const s of row) visit(s);
 }
+/**
+* Iterate the populated cells of a reference, honouring a cross-sheet qualifier (an
+* absent `eachCellOn` ⇒ no cross-sheet support ⇒ the foreign range is empty).
+*/
 function refEach(v, ctx, visit) {
 	if (v.sheet !== void 0) ctx.eachCellOn?.(v.sheet, v.rect, visit);
 	else ctx.eachCell(v.rect, visit);
 }
+/** Read one absolute cell on a reference's sheet (the current sheet when `sheet` is unset). */
 function refGet(sheet, ctx, row, col) {
 	return sheet !== void 0 ? ctx.getCellOn?.(sheet, row, col) ?? BLANK : ctx.getCell(row, col);
 }
+/**
+* §18.17.3 — number coercion. blank → 0, logical → 1/0, a numeric string → its
+* number (Excel parses `"5"` and `" 5 "` leniently); non-numeric text → `#VALUE!`.
+* An error propagates (returned as the {@link FErr}); references are dereferenced first.
+*/
 function toNumber(v, ctx) {
 	const s = deref(v, ctx);
 	switch (s.t) {
@@ -67,6 +92,11 @@ function toNumber(v, ctx) {
 		}
 	}
 }
+/**
+* §18.17.3 — text coercion. A number formats with the shortest round-trip
+* representation, a logical as `TRUE`/`FALSE`, blank as the empty string. Errors
+* propagate (returned as the {@link FErr}).
+*/
 function toText(v, ctx) {
 	const s = deref(v, ctx);
 	switch (s.t) {

package/dist/esm/excel/header-footer.d.ts

@@ -1,2 +1,11 @@
 import { BodyElement } from '../core/document-model/index.js';
+/**
+ * Expand a print header/footer `&`-code string (E-SHEET W4) into header/footer band
+ * content — one aligned paragraph per non-empty left/centre/right region — or `[]`
+ * when every region is empty. `&P`/`&N` become dynamic PAGE/NUMPAGES field runs the
+ * renderer resolves per page; non-deterministic or unsupported codes are dropped.
+ *
+ * @param formatString The raw `&`-code format string.
+ * @param sheetName    The worksheet tab name, substituted for `&A`.
+ */
 export declare function buildHeaderFooterContent(formatString: string, sheetName: string): Array<BodyElement>;

package/dist/esm/excel/header-footer.js

@@ -1,4 +1,13 @@
 //#region src/excel/header-footer.ts
+/**
+* Expand a print header/footer `&`-code string (E-SHEET W4) into header/footer band
+* content — one aligned paragraph per non-empty left/centre/right region — or `[]`
+* when every region is empty. `&P`/`&N` become dynamic PAGE/NUMPAGES field runs the
+* renderer resolves per page; non-deterministic or unsupported codes are dropped.
+*
+* @param formatString The raw `&`-code format string.
+* @param sheetName    The worksheet tab name, substituted for `&A`.
+*/
 function buildHeaderFooterContent(formatString, sheetName) {
 	const regions = parseHeaderFooterString(formatString, sheetName);
 	const out = [];

package/dist/esm/excel/number-format.d.ts

@@ -1,3 +1,37 @@
+/**
+ * Render a cell's raw stored value through its number format (§18.8.30 built-ins
+ * and §18.8.31 custom codes). Handles `General`, text (`@`), the built-in date /
+ * time formats, custom date codes, and the numeric placeholder grammar (`0` `#`
+ * `,` `.` `%`, scientific notation, quoted literals, `;`-separated sections). An
+ * unknown id, or a value that does not parse as a number, falls back to a plain
+ * render of `rawValue`.
+ *
+ * @param rawValue      The cell's raw stored value (a serial for dates).
+ * @param numFmtId      The number-format id from the cell's `cellXf`.
+ * @param customFormats Custom format codes by id (from `<numFmts>`).
+ * @param date1904      The workbook date epoch (1904 vs the 1900 default).
+ * @returns The formatted display string.
+ */
 export declare function applyNumberFormat(rawValue: string, numFmtId: number, customFormats: ReadonlyMap<number, string>, date1904?: boolean): string;
+/**
+ * Excel serial date → JS `Date`. The default 1900 epoch uses 1899-12-30 as day 0
+ * (so serial 1 is 1900-01-01) and inherits the Lotus 1-2-3 leap-year bug: serial 60
+ * is considered "1900-02-29" which never existed. For serial ≥ 61 the simple
+ * formula is exact; values < 60 are vanishingly rare in business sheets (and our
+ * render is approximate anyway).
+ *
+ * The 1904 epoch (legacy Mac Excel) uses 1904-01-01 as day 0 and has no leap bug.
+ * Files saved with `<workbookPr date1904="1"/>` store dates offset by exactly 1462
+ * days from the 1900-epoch interpretation.
+ */
 export declare function excelSerialToDate(serial: number, date1904: boolean): Date;
+/**
+ * The inverse over a UTC calendar date: `(year, month0, day)` → the integer Excel
+ * serial day, using the same epoch. Round-trips {@link excelSerialToDate} exactly
+ * for an integer serial (the time-of-day is zero), so a serial → parts → serial
+ * loop is stable. Used by the formula engine's date functions and the `timePeriod`
+ * windows (E-SHEET W9) to map an injected reference date into serial space.
+ *
+ * @param month0 The 0-indexed month (0 = January).
+ */
 export declare function excelSerialFromUtcParts(year: number, month0: number, day: number, date1904: boolean): number;

package/dist/esm/excel/number-format.js

@@ -28,6 +28,20 @@ var BUILTIN_DATE_FORMATS = new Map([
 	[46, "[h]:mm:ss"],
 	[47, "mm:ss.0"]
 ]);
+/**
+* Render a cell's raw stored value through its number format (§18.8.30 built-ins
+* and §18.8.31 custom codes). Handles `General`, text (`@`), the built-in date /
+* time formats, custom date codes, and the numeric placeholder grammar (`0` `#`
+* `,` `.` `%`, scientific notation, quoted literals, `;`-separated sections). An
+* unknown id, or a value that does not parse as a number, falls back to a plain
+* render of `rawValue`.
+*
+* @param rawValue      The cell's raw stored value (a serial for dates).
+* @param numFmtId      The number-format id from the cell's `cellXf`.
+* @param customFormats Custom format codes by id (from `<numFmts>`).
+* @param date1904      The workbook date epoch (1904 vs the 1900 default).
+* @returns The formatted display string.
+*/
 function applyNumberFormat(rawValue, numFmtId, customFormats, date1904 = false) {
 	if (rawValue.length === 0) return "";
 	if (numFmtId === 0) return defaultNumberRender(rawValue);
@@ -41,11 +55,31 @@ function applyNumberFormat(rawValue, numFmtId, customFormats, date1904 = false)
 	if (format === "General") return defaultNumberRender(rawValue);
 	return applyFormatString(rawValue, format);
 }
+/**
+* Excel serial date → JS `Date`. The default 1900 epoch uses 1899-12-30 as day 0
+* (so serial 1 is 1900-01-01) and inherits the Lotus 1-2-3 leap-year bug: serial 60
+* is considered "1900-02-29" which never existed. For serial ≥ 61 the simple
+* formula is exact; values < 60 are vanishingly rare in business sheets (and our
+* render is approximate anyway).
+*
+* The 1904 epoch (legacy Mac Excel) uses 1904-01-01 as day 0 and has no leap bug.
+* Files saved with `<workbookPr date1904="1"/>` store dates offset by exactly 1462
+* days from the 1900-epoch interpretation.
+*/
 function excelSerialToDate(serial, date1904) {
 	const ms = serial * 86400 * 1e3;
 	if (date1904) return new Date(Date.UTC(1904, 0, 1) + ms);
 	return new Date(Date.UTC(1899, 11, 30) + ms);
 }
+/**
+* The inverse over a UTC calendar date: `(year, month0, day)` → the integer Excel
+* serial day, using the same epoch. Round-trips {@link excelSerialToDate} exactly
+* for an integer serial (the time-of-day is zero), so a serial → parts → serial
+* loop is stable. Used by the formula engine's date functions and the `timePeriod`
+* windows (E-SHEET W9) to map an injected reference date into serial space.
+*
+* @param month0 The 0-indexed month (0 = January).
+*/
 function excelSerialFromUtcParts(year, month0, day, date1904) {
 	const epoch = date1904 ? Date.UTC(1904, 0, 1) : Date.UTC(1899, 11, 30);
 	return Math.round((Date.UTC(year, month0, day) - epoch) / 864e5);

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

@@ -1,2 +1,10 @@
 import { PivotTable } from '../core/spreadsheet-model/index.js';
+/**
+ * Parse `xl/pivotTables/pivotTableN.xml` (§18.10.1.73) into a {@link PivotTable}:
+ * the output `<location>` (range + header/data offsets), the banded-style flags,
+ * and the row/column total markers derived from `<rowItems>`/`<colItems>` (so the
+ * reader can band the region in the pivot palette — E-PIVOT). The output cells are
+ * already cached in the worksheet, so they render as a normal grid. Returns
+ * undefined when the root or its `ref` is missing.
+ */
 export declare function parsePivotTablePart(data: Uint8Array): PivotTable | undefined;

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

@@ -9,6 +9,14 @@ var parser = new XMLParser({
 	parseTagValue: false,
 	removeNSPrefix: true
 });
+/**
+* Parse `xl/pivotTables/pivotTableN.xml` (§18.10.1.73) into a {@link PivotTable}:
+* the output `<location>` (range + header/data offsets), the banded-style flags,
+* and the row/column total markers derived from `<rowItems>`/`<colItems>` (so the
+* reader can band the region in the pivot palette — E-PIVOT). The output cells are
+* already cached in the worksheet, so they render as a normal grid. Returns
+* undefined when the root or its `ref` is missing.
+*/
 function parsePivotTablePart(data) {
 	const def = asObj(parser.parse(decoder.decode(data))["pivotTableDefinition"]);
 	if (!def) return void 0;

package/dist/esm/excel/print-model.d.ts

@@ -1,11 +1,34 @@
 import { BodyElement, SectionProperties, Table } from '../core/document-model/index.js';
 import { CellRange, DefinedName, ParsedWorksheet, SheetRichRun, WorksheetCell, XlsxStyles } from './index.js';
 import { SheetHyperlink, SheetSlicer } from '../core/ir/sheet.js';
+/**
+ * Excel "character width" → twips. Calibri 11pt default Maximum Digit Width is
+ * ~7 px ≈ 5.25 pt ≈ 105 twips. This is a coarse approximation but the auto-fit
+ * pass refines column widths against the actual cell text anyway.
+ */
 export declare const TWIPS_PER_EXCEL_CHAR = 105;
+/**
+ * Excel's default column width is 8.43 "characters" ≈ 64px ≈ 960 twips. Used for
+ * columns without an explicit `<col width="..">`.
+ */
 export declare const DEFAULT_COL_TWIPS = 960;
+/**
+ * Excel's default row height is ~15pt = 300 twips. Used (for the `fitToHeight`
+ * estimate) for rows without an explicit `<row ht="..">`.
+ */
 export declare const DEFAULT_ROW_TWIPS = 300;
+/**
+ * Build the page section (paper size + margins) from a worksheet's `<pageSetup>`
+ * / `<pageMargins>`. Returns `undefined` when neither is set, so the renderer
+ * applies its A4 default.
+ */
 export declare function sectionFromWorksheet(worksheet: ParsedWorksheet): SectionProperties | undefined;
+/**
+ * ECMA-376 §18.2.5 — resolve the sheet-scoped `_xlnm.Print_Area` defined name
+ * (`localSheetId` = the sheet's 0-based index) into a clipping range.
+ */
 export declare function resolvePrintArea(definedNames: ReadonlyArray<DefinedName>, sheetIdx: number): CellRange | undefined;
+/** ECMA-376 §18.2.5 — `_xlnm.Print_Titles` → the repeated row range (0-indexed). */
 export declare function resolvePrintTitleRows(definedNames: ReadonlyArray<DefinedName>, sheetIdx: number): {
     readonly startRow: number;
     readonly endRow: number;
@@ -24,7 +47,40 @@ interface PrintModelOptions {
     readonly sharedStringRuns?: ReadonlyArray<ReadonlyArray<SheetRichRun> | undefined>;
     readonly now?: Date;
 }
+/**
+ * Project one worksheet's grid into Flow body elements — a single {@link Table}
+ * (or, when the sheet is wider than the page, several column-banded tables). The
+ * full print model lives here: the used-range/print-area window, merge handling,
+ * the style cascade (fonts/fills/borders/alignment), print scaling, conditional
+ * formatting, sparklines, table/pivot banding, overflow and rotation. Memory- and
+ * text-budget-bounded against untrusted input.
+ *
+ * @param worksheet    The parsed grid + per-sheet geometry.
+ * @param sharedStrings The workbook shared-string table (`t="s"` cells index it).
+ * @param styles       The workbook style table (cellXfs + fonts/fills/borders).
+ * @param date1904     The 1904 date system flag (serial-to-date epoch).
+ * @param print        The print-model knobs (print area, gridlines, title rows, …).
+ * @returns The body elements (one table block, or banded tables); empty for a
+ *   blank or empty-print-area sheet.
+ */
 export declare function worksheetToBody(worksheet: ParsedWorksheet, sharedStrings: ReadonlyArray<string>, styles: XlsxStyles, date1904: boolean, print: PrintModelOptions): Array<BodyElement>;
+/**
+ * Resolve a cell's displayed text from its RAW stored value: shared-string and
+ * inline-string lookup, boolean → `TRUE`/`FALSE`, and the number-format pass
+ * (§18.8) for numeric cells. Error/string/date cells pass through verbatim.
+ *
+ * @param cell         The parsed cell.
+ * @param sharedStrings The shared-string table for `t="s"` cells.
+ * @param styles       The style table (for the cell's number format).
+ * @param date1904     The 1904 date system flag.
+ * @returns The resolved display string.
+ */
 export declare function resolveCellText(cell: WorksheetCell, sharedStrings: ReadonlyArray<string>, styles: XlsxStyles, date1904: boolean): string;
+/**
+ * Project a slicer panel (E-SHEET SV2) into a styled mini-{@link Table} emitted
+ * after the grid: a caption header spanning the button columns, then one button
+ * cell per item — the slicer accent fill + white text when selected, a light
+ * band when not; the last row padded so every row keeps the column count.
+ */
 export declare function slicerTable(slicer: SheetSlicer): Table;
 export {};

package/dist/esm/excel/print-model.js

@@ -16,6 +16,11 @@ var PAPER_SIZES_TWIPS = new Map([
 	[70, [5953, 8392]]
 ]);
 var DEFAULT_PAPER_TWIPS = [11906, 16838];
+/**
+* Build the page section (paper size + margins) from a worksheet's `<pageSetup>`
+* / `<pageMargins>`. Returns `undefined` when neither is set, so the renderer
+* applies its A4 default.
+*/
 function sectionFromWorksheet(worksheet) {
 	const pageSize = pageSizeFromSetup(worksheet.pageSetup);
 	const margins = marginsFromXlsx(worksheet.pageMargins);
@@ -52,9 +57,14 @@ function marginsFromXlsx(margins) {
 }
 var PRINT_AREA_NAME = "_xlnm.Print_Area";
 var PRINT_TITLES_NAME = "_xlnm.Print_Titles";
+/**
+* ECMA-376 §18.2.5 — resolve the sheet-scoped `_xlnm.Print_Area` defined name
+* (`localSheetId` = the sheet's 0-based index) into a clipping range.
+*/
 function resolvePrintArea(definedNames, sheetIdx) {
 	for (const dn of definedNames) if (dn.name === PRINT_AREA_NAME && dn.localSheetId === sheetIdx) return parseAreaRef(dn.value);
 }
+/** ECMA-376 §18.2.5 — `_xlnm.Print_Titles` → the repeated row range (0-indexed). */
 function resolvePrintTitleRows(definedNames, sheetIdx) {
 	for (const dn of definedNames) if (dn.name === PRINT_TITLES_NAME && dn.localSheetId === sheetIdx) return parseTitleRowRange(dn.value);
 }
@@ -97,6 +107,22 @@ function scaleRunFont(props, scale) {
 	};
 }
 var MAX_SHEET_TEXT_CHARS = 1e6;
+/**
+* Project one worksheet's grid into Flow body elements — a single {@link Table}
+* (or, when the sheet is wider than the page, several column-banded tables). The
+* full print model lives here: the used-range/print-area window, merge handling,
+* the style cascade (fonts/fills/borders/alignment), print scaling, conditional
+* formatting, sparklines, table/pivot banding, overflow and rotation. Memory- and
+* text-budget-bounded against untrusted input.
+*
+* @param worksheet    The parsed grid + per-sheet geometry.
+* @param sharedStrings The workbook shared-string table (`t="s"` cells index it).
+* @param styles       The workbook style table (cellXfs + fonts/fills/borders).
+* @param date1904     The 1904 date system flag (serial-to-date epoch).
+* @param print        The print-model knobs (print area, gridlines, title rows, …).
+* @returns The body elements (one table block, or banded tables); empty for a
+*   blank or empty-print-area sheet.
+*/
 function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 	if (worksheet.maxRow < 0 || worksheet.maxColumn < 0) return [];
 	let usedRow = -1;
@@ -384,6 +410,17 @@ function makeVerticalContinuation(merge, colWindowEnd, absR, rowWindowEnd) {
 		}]
 	};
 }
+/**
+* Resolve a cell's displayed text from its RAW stored value: shared-string and
+* inline-string lookup, boolean → `TRUE`/`FALSE`, and the number-format pass
+* (§18.8) for numeric cells. Error/string/date cells pass through verbatim.
+*
+* @param cell         The parsed cell.
+* @param sharedStrings The shared-string table for `t="s"` cells.
+* @param styles       The style table (for the cell's number format).
+* @param date1904     The 1904 date system flag.
+* @returns The resolved display string.
+*/
 function resolveCellText(cell, sharedStrings, styles, date1904) {
 	if (cell.type === "inlineStr") return cell.inlineText ?? "";
 	if (cell.type === "s") {
@@ -698,6 +735,12 @@ function cellHasContent(cell) {
 var SLICER_WIDTH_PT = 108;
 var SLICER_ROW_PT = 16;
 var SLICER_UNSELECTED_HEX = "F2F2F2";
+/**
+* Project a slicer panel (E-SHEET SV2) into a styled mini-{@link Table} emitted
+* after the grid: a caption header spanning the button columns, then one button
+* cell per item — the slicer accent fill + white text when selected, a light
+* band when not; the last row padded so every row keeps the column count.
+*/
 function slicerTable(slicer) {
 	const cols = Math.max(1, slicer.columnCount);
 	const colWidthPt = SLICER_WIDTH_PT / cols;

package/dist/esm/excel/shared-strings-parser.d.ts

@@ -1,6 +1,19 @@
 import { SheetRichRun } from '../core/spreadsheet-model/index.js';
+/**
+ * The flattened text of every shared string (a cell with `t="s"` indexes into it),
+ * plus — for the strings that carry per-run formatting — the parsed rich runs
+ * (E-SHEET W6). `runs[i]` is undefined unless si `i` has ≥ 2 runs OR a single run
+ * that actually sets formatting, so the common plain-text case stays cheap.
+ */
 export interface SharedStrings {
+    /** The flattened text of each shared string, parallel to the `<si>` order. */
     readonly texts: ReadonlyArray<string>;
+    /** Per-index rich runs, parallel to {@link SharedStrings.texts}; `undefined` for plain strings. */
     readonly runs: ReadonlyArray<ReadonlyArray<SheetRichRun> | undefined>;
 }
+/**
+ * Parse `xl/sharedStrings.xml` (§18.4.8) into the deduplicated string table plus,
+ * for rich strings, their per-run formatting. Each string is capped to the Excel
+ * cell limit (32 767 chars).
+ */
 export declare function parseSharedStrings(data: Uint8Array): SharedStrings;

package/dist/esm/excel/shared-strings-parser.js

@@ -14,6 +14,11 @@ var MAX_CELL_CHARS = 32767;
 function capLen(s) {
 	return s.length > MAX_CELL_CHARS ? s.slice(0, MAX_CELL_CHARS) : s;
 }
+/**
+* Parse `xl/sharedStrings.xml` (§18.4.8) into the deduplicated string table plus,
+* for rich strings, their per-run formatting. Each string is capped to the Excel
+* cell limit (32 767 chars).
+*/
 function parseSharedStrings(data) {
 	const xml = decoder.decode(data);
 	const sst = parser.parse(xml)["sst"];

package/dist/esm/excel/sheet-drawing.d.ts

@@ -1,21 +1,55 @@
 import { OpcPackage } from '../core/opc/index.js';
 import { ParsedWorksheet } from '../core/spreadsheet-model/index.js';
+/** §20.5 — a chart frame anchored over the grid, sized from its cell-range anchor. */
 export interface SheetChartRef {
+    /**
+     * The resolved chart part path (`'xl/charts/chart1.xml'`) — globally unique, used
+     * as the FlowDoc charts key and the `ChartBlock.chartRelId`.
+     */
     readonly chartPartPath: string;
     readonly widthPt: number;
     readonly heightPt: number;
+    /** Anchor top row (0-based) — used only to order charts on the sheet. */
     readonly anchorRow: number;
 }
+/**
+ * §20.5.2.1 `xdr:pic` — a picture anchored over the grid. The reader reads the
+ * resolved media part's bytes into the SheetDoc resource store.
+ */
 export interface SheetPicture {
+    /** The resolved media part path; the reader loads its bytes into the resource store. */
     readonly imagePartPath: string;
     readonly widthPt: number;
     readonly heightPt: number;
+    /** Anchor top row (0-based) — used only to order pictures on the sheet. */
     readonly anchorRow: number;
 }
+/** Both kinds of anchored frame the drawing yields, anchor-ordered. */
 export interface SheetDrawing {
     readonly charts: Array<SheetChartRef>;
     readonly pictures: Array<SheetPicture>;
 }
+/**
+ * Parse a `xl/drawings/drawingN.xml` part (§20.5.2.35/.33/.1 — `xdr:twoCellAnchor`
+ * / `oneCellAnchor` / `absoluteAnchor`) into the {@link SheetDrawing} it yields.
+ * Each anchor frames either a chart (`graphicFrame`) or a picture (`xdr:pic`); both
+ * are sized from the anchor and returned anchor-ordered.
+ *
+ * @param drawingXml      The drawing part bytes.
+ * @param drawingPartPath The drawing part path, for resolving its relationships.
+ * @param pkg             The OPC package, used to resolve relId → part path.
+ * @param worksheet       The host worksheet, for the column/row track geometry.
+ */
 export declare function parseSheetDrawing(drawingXml: Uint8Array, drawingPartPath: string, pkg: OpcPackage, worksheet: ParsedWorksheet): SheetDrawing;
+/**
+ * Build a `col → width-in-points` accessor: a `<col>` override (Excel "chars")
+ * where present, else the default — the same conversions the print model uses.
+ * Exported so the sheet-shape parser (E-SHEET W2) sizes shape anchors with the same
+ * track geometry.
+ */
 export declare function makeColWidthPt(ws: ParsedWorksheet): (col: number) => number;
+/**
+ * Build a `row → height-in-points` accessor: the explicit row height where present,
+ * else the default. Pairs with {@link makeColWidthPt} for the anchor track geometry.
+ */
 export declare function makeRowHeightPt(ws: ParsedWorksheet): (row: number) => number;

package/dist/esm/excel/sheet-drawing.js

@@ -10,6 +10,17 @@ var parser = new XMLParser({
 	parseTagValue: false
 });
 var TWIPS_PER_PT = 20;
+/**
+* Parse a `xl/drawings/drawingN.xml` part (§20.5.2.35/.33/.1 — `xdr:twoCellAnchor`
+* / `oneCellAnchor` / `absoluteAnchor`) into the {@link SheetDrawing} it yields.
+* Each anchor frames either a chart (`graphicFrame`) or a picture (`xdr:pic`); both
+* are sized from the anchor and returned anchor-ordered.
+*
+* @param drawingXml      The drawing part bytes.
+* @param drawingPartPath The drawing part path, for resolving its relationships.
+* @param pkg             The OPC package, used to resolve relId → part path.
+* @param worksheet       The host worksheet, for the column/row track geometry.
+*/
 function parseSheetDrawing(drawingXml, drawingPartPath, pkg, worksheet) {
 	const root = parser.parse(new TextDecoder().decode(drawingXml))["wsDr"];
 	if (!root || typeof root !== "object") return {
@@ -120,12 +131,22 @@ function spanPt(from, fromOffPt, to, toOffPt, trackPt) {
 	for (let i = from; i < to; i++) span += trackPt(i);
 	return span - fromOffPt + toOffPt;
 }
+/**
+* Build a `col → width-in-points` accessor: a `<col>` override (Excel "chars")
+* where present, else the default — the same conversions the print model uses.
+* Exported so the sheet-shape parser (E-SHEET W2) sizes shape anchors with the same
+* track geometry.
+*/
 function makeColWidthPt(ws) {
 	return (col) => {
 		for (const c of ws.columns) if (col >= c.min - 1 && col <= c.max - 1) return c.widthChars * 105 / TWIPS_PER_PT;
 		return 960 / TWIPS_PER_PT;
 	};
 }
+/**
+* Build a `row → height-in-points` accessor: the explicit row height where present,
+* else the default. Pairs with {@link makeColWidthPt} for the anchor track geometry.
+*/
 function makeRowHeightPt(ws) {
 	return (row) => {
 		for (const r of ws.rowHeights) if (r.row === row) return r.heightPt;

package/dist/esm/excel/sheet-shape-parser.d.ts

@@ -1,4 +1,16 @@
 import { ShapeBlock } from '../core/document-model/index.js';
 import { ColorResolver } from '../core/drawingml/colors.js';
 import { ParsedWorksheet } from '../core/spreadsheet-model/index.js';
+/**
+ * Parse a drawing's `xdr:sp` shape anchors (§20.5.2.30) into anchor-ordered
+ * {@link ShapeBlock}s (E-SHEET W2), reusing the shared DrawingML geometry / fill /
+ * line / text readers. A shape's box comes from its sheet anchor (from/to tracks),
+ * not its `a:xfrm`. Returns `[]` when the drawing has no shapes (chart/picture-only),
+ * so the reader's gate keeps non-shape sheets off this second parse.
+ *
+ * @param drawingXml The drawing part bytes (re-parsed via `parseXml` for the
+ *                   preserveOrder tree the shape readers expect).
+ * @param worksheet  The host worksheet, for the column/row track geometry.
+ * @param colors     The theme colour resolver threaded into fill/line parsing.
+ */
 export declare function parseSheetShapes(drawingXml: Uint8Array, worksheet: ParsedWorksheet, colors: ColorResolver): Array<ShapeBlock>;

package/dist/esm/excel/sheet-shape-parser.js

@@ -10,6 +10,18 @@ var ANCHOR_KINDS = [
 	"xdr:oneCellAnchor",
 	"xdr:absoluteAnchor"
 ];
+/**
+* Parse a drawing's `xdr:sp` shape anchors (§20.5.2.30) into anchor-ordered
+* {@link ShapeBlock}s (E-SHEET W2), reusing the shared DrawingML geometry / fill /
+* line / text readers. A shape's box comes from its sheet anchor (from/to tracks),
+* not its `a:xfrm`. Returns `[]` when the drawing has no shapes (chart/picture-only),
+* so the reader's gate keeps non-shape sheets off this second parse.
+*
+* @param drawingXml The drawing part bytes (re-parsed via `parseXml` for the
+*                   preserveOrder tree the shape readers expect).
+* @param worksheet  The host worksheet, for the column/row track geometry.
+* @param colors     The theme colour resolver threaded into fill/line parsing.
+*/
 function parseSheetShapes(drawingXml, worksheet, colors) {
 	const wsDr = parseXml(drawingXml).find((n) => poIs(n, "xdr:wsDr"));
 	if (!wsDr) return [];

package/dist/esm/excel/sheet-to-flow.d.ts

@@ -1,6 +1,25 @@
 import { FlowDoc } from '../core/ir/flow.js';
 import { SheetDoc } from '../core/ir/sheet.js';
+/**
+ * Projection knobs (E-SHEET W9).
+ */
 export interface ProjectSheetOptions {
+    /**
+     * The injected reference date that drives conditional-format `timePeriod`
+     * windows and `TODAY()`/`NOW()` in `expression` rules. Omitted ⇒ those
+     * clock-relative constructs no-op, so the projection stays deterministic and
+     * byte-identical to before.
+     */
     readonly now?: Date;
 }
+/**
+ * Project a {@link SheetDoc} into a {@link FlowDoc} (E-SHEET SA2): each grid sheet
+ * becomes flow blocks (a table + chart/picture/shape/slicer frames, then comment
+ * / control listings), with sheets after the first starting on a new page. The
+ * first sheet's page geometry + header/footer drive the document section.
+ *
+ * @param sheet   The SpreadsheetML IR tree.
+ * @param options Projection knobs (the W9 reference date).
+ * @returns The format-neutral flow document the render path consumes.
+ */
 export declare function projectSheetDoc(sheet: SheetDoc, options?: ProjectSheetOptions): FlowDoc;

package/dist/esm/excel/sheet-to-flow.js

@@ -6,6 +6,16 @@ import { buildHeaderFooterContent } from "./header-footer.js";
 //#region src/excel/sheet-to-flow.ts
 var HEADER_REL = "_xlsxHeaderDefault";
 var FOOTER_REL = "_xlsxFooterDefault";
+/**
+* Project a {@link SheetDoc} into a {@link FlowDoc} (E-SHEET SA2): each grid sheet
+* becomes flow blocks (a table + chart/picture/shape/slicer frames, then comment
+* / control listings), with sheets after the first starting on a new page. The
+* first sheet's page geometry + header/footer drive the document section.
+*
+* @param sheet   The SpreadsheetML IR tree.
+* @param options Projection knobs (the W9 reference date).
+* @returns The format-neutral flow document the render path consumes.
+*/
 function projectSheetDoc(sheet, options = {}) {
 	const body = [];
 	let firstSheetSection;

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

@@ -1,15 +1,38 @@
+/**
+ * §18.3.1 (2009/9/main) `<slicer>` — one slicer panel. `cacheName` (`@cache`) keys
+ * into the workbook's slicer caches; `caption` (`@caption`) titles the box.
+ */
 export interface SlicerDef {
     readonly name: string;
+    /** The slicer-cache name (`@cache`) binding this panel to its source. */
     readonly cacheName: string;
     readonly caption: string;
     readonly columnCount: number;
     readonly styleName?: string;
 }
+/**
+ * `<slicerCacheDefinition>` — binds a slicer to its source. A native-table slicer
+ * carries an `<x14:tableSlicerCache tableId column>` (the table + column whose
+ * values are the buttons). `sourceName` is the field/column name.
+ */
 export interface SlicerCacheDef {
     readonly name: string;
+    /** The source field/column name. */
     readonly sourceName?: string;
+    /** The source table id (a native-table slicer), matched against a parsed table part's id. */
     readonly tableId?: number;
+    /** The source column offset within that table. */
     readonly columnId?: number;
 }
+/**
+ * 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.
+ */
 export declare function parseSlicerPart(data: Uint8Array): Array<SlicerDef>;
+/**
+ * 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.
+ */
 export declare function parseSlicerCachePart(data: Uint8Array): SlicerCacheDef | undefined;