reamkit 1.15.1 → 1.15.3

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

@@ -1,9 +1,23 @@
 import { eighthPtToPt, halfPtToPt, pt, twipsToPt } from "../core/ir/units.js";
+import { FEATURES } from "../core/ir/features.js";
 import { parseAreaRef, parseTitleRowRange } from "./defined-name-ref.js";
 import { applyNumberFormat } from "./number-format.js";
 import "./index.js";
 import { bandedTables, computeColumnBands } from "./column-bands.js";
 import { buildConditionalFormatter } from "./conditional-format.js";
+/**
+* Excel insets a cell's text by ~2 px each side (1.5 pt at 96 DPI). The layout
+* engine's default is a word processor's 108 twips (5.4 pt), which is nearly
+* four times as much.
+*/
+var EXCEL_CELL_INSET_PT = 1.5;
+/**
+* ECMA-376 §18.3.1.81 — the row height Excel uses when a sheet declares no
+* `<sheetFormatPr defaultRowHeight>`: 15pt, the line height of its default
+* theme font (Calibri 11). Independent of whatever font we end up rendering
+* with — the height belongs to the document, not to the typesetter.
+*/
+var EXCEL_DEFAULT_ROW_HEIGHT_PT = 15;
 var TWIPS_PER_POINT = 20;
 var TWIPS_PER_INCH = 1440;
 var PAPER_SIZES_TWIPS = new Map([
@@ -16,13 +30,22 @@ 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>`.
+*
+* Margins are always set, to Excel's own defaults when the worksheet declares
+* none (§18.3.1.62) — the renderer's fallback is a word processor's inch, which
+* is not what a spreadsheet prints. The paper size is left unset when the
+* worksheet names none, because there the file genuinely holds no answer: Excel
+* picks by locale and printer, and the renderer's deterministic A4 is as good
+* as anything we could invent.
+*/
 function sectionFromWorksheet(worksheet) {
 	const pageSize = pageSizeFromSetup(worksheet.pageSetup);
-	const margins = marginsFromXlsx(worksheet.pageMargins);
-	if (!pageSize && !margins) return void 0;
 	return {
 		...pageSize ? { pageSize } : {},
-		...margins ? { margins } : {},
+		margins: marginsFromXlsx(worksheet.pageMargins),
 		headers: [],
 		footers: []
 	};
@@ -39,8 +62,23 @@ function pageSizeFromSetup(setup) {
 		orientation
 	};
 }
+/**
+* ECMA-376 §18.3.1.62 — the page margins Excel writes when the user has not
+* touched them, in inches. A worksheet may omit `<pageMargins>` entirely, and
+* falling through to the renderer's default (a word processor's 1 inch) put the
+* grid 0.3 inch — 21.6 pt — right of where Excel and LibreOffice print it, on
+* every such sheet.
+*/
+var EXCEL_DEFAULT_MARGINS = {
+	left: twipsToPt(Math.round(.7 * TWIPS_PER_INCH)),
+	right: twipsToPt(Math.round(.7 * TWIPS_PER_INCH)),
+	top: twipsToPt(Math.round(.75 * TWIPS_PER_INCH)),
+	bottom: twipsToPt(Math.round(.75 * TWIPS_PER_INCH)),
+	header: twipsToPt(Math.round(.3 * TWIPS_PER_INCH)),
+	footer: twipsToPt(Math.round(.3 * TWIPS_PER_INCH))
+};
 function marginsFromXlsx(margins) {
-	if (!margins) return void 0;
+	if (!margins) return EXCEL_DEFAULT_MARGINS;
 	return {
 		top: twipsToPt(Math.round(margins.topInches * TWIPS_PER_INCH)),
 		right: twipsToPt(Math.round(margins.rightInches * TWIPS_PER_INCH)),
@@ -52,9 +90,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);
 }
@@ -63,16 +106,16 @@ function sheetContentWidthTwips(worksheet) {
 	const pageSize = pageSizeFromSetup(worksheet.pageSetup);
 	const pageWidthTwips = pageSize ? Math.round(pageSize.width * 20) : DEFAULT_PAPER_TWIPS[0];
 	const margins = marginsFromXlsx(worksheet.pageMargins);
-	const left = margins ? Math.round(margins.left * 20) : TWIPS_PER_INCH;
-	const right = margins ? Math.round(margins.right * 20) : TWIPS_PER_INCH;
+	const left = Math.round(margins.left * 20);
+	const right = Math.round(margins.right * 20);
 	return Math.max(TWIPS_PER_INCH / 2, pageWidthTwips - left - right);
 }
 function sheetContentHeightTwips(worksheet) {
 	const pageSize = pageSizeFromSetup(worksheet.pageSetup);
 	const pageHeightTwips = pageSize ? Math.round(pageSize.height * 20) : DEFAULT_PAPER_TWIPS[1];
 	const margins = marginsFromXlsx(worksheet.pageMargins);
-	const top = margins ? Math.round(margins.top * 20) : TWIPS_PER_INCH;
-	const bottom = margins ? Math.round(margins.bottom * 20) : TWIPS_PER_INCH;
+	const top = Math.round(margins.top * 20);
+	const bottom = Math.round(margins.bottom * 20);
 	return Math.max(TWIPS_PER_INCH / 2, pageHeightTwips - top - bottom);
 }
 function computePrintScale(worksheet, totalGridTwips, contentWidthTwips, totalGridHeightTwips, contentHeightTwips) {
@@ -97,6 +140,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;
@@ -128,11 +187,34 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 	}
 	if (rowEnd < rowStart || colEnd < colStart) return [];
 	const MAX_GRID_COLS = 1024;
-	const rowCount = Math.min(rowEnd - rowStart + 1, 5e4);
-	const colCount = Math.min(colEnd - colStart + 1, MAX_GRID_COLS);
+	const MAX_GRID_ROWS = 5e4;
+	const MAX_GRID_CELLS = 1e6;
+	const wantRows = rowEnd - rowStart + 1;
+	const wantCols = colEnd - colStart + 1;
+	let colCount = Math.min(wantCols, MAX_GRID_COLS);
+	let rowCount = Math.max(1, Math.min(wantRows, MAX_GRID_ROWS, Math.floor(MAX_GRID_CELLS / colCount)));
+	if (rowCount < wantRows) rowCount = Math.max(1, lastContentRow(worksheet, rowStart, rowCount, colStart, colCount) + 1);
+	if (colCount < wantCols) colCount = Math.max(1, lastContentColumn(worksheet, rowStart, rowCount, colStart, colCount) + 1);
+	if (rowCount < wantRows) print.losses?.push({
+		severity: "dropped",
+		feature: FEATURES.tables,
+		detail: `grid clipped to the first ${rowCount} rows of ${wantRows} in the used range (memory guard)`,
+		...print.sheetName ? { where: `sheet "${print.sheetName}"` } : {}
+	});
+	if (colCount < wantCols) print.losses?.push({
+		severity: "dropped",
+		feature: FEATURES.tables,
+		detail: `grid clipped to the first ${colCount} columns of ${wantCols} in the used range (memory guard)`,
+		...print.sheetName ? { where: `sheet "${print.sheetName}"` } : {}
+	});
 	const rowWindowEnd = rowStart + rowCount - 1;
 	const colWindowEnd = colStart + colCount - 1;
+	const defaultRowTwips = Math.round((worksheet.defaultRowHeightPt ?? EXCEL_DEFAULT_ROW_HEIGHT_PT) * TWIPS_PER_POINT);
 	const rowHeightMap = /* @__PURE__ */ new Map();
+	for (let r = 0; r < rowCount; r++) rowHeightMap.set(r, {
+		heightTwips: defaultRowTwips,
+		heightRule: "atLeast"
+	});
 	for (const h of worksheet.rowHeights) {
 		const local = h.row - rowStart;
 		if (local < 0 || local >= rowCount) continue;
@@ -158,9 +240,11 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 		const cEnd = Math.min(m.endColumn, colWindowEnd);
 		for (let r = Math.max(m.startRow, rowStart); r <= rEnd; r++) for (let c = Math.max(m.startColumn, colStart); c <= cEnd; c++) if (!(r === m.startRow && c === m.startColumn)) insideMerge.add(key(r, c));
 	}
-	const columnWidths = new Array(colCount).fill(960);
+	const defaultColChars = worksheet.defaultColWidthChars ?? worksheet.baseColWidthChars;
+	const defaultColTwips = defaultColChars !== void 0 ? Math.round(defaultColChars * 105 + 75) : 960;
+	const columnWidths = new Array(colCount).fill(defaultColTwips);
 	for (const col of worksheet.columns) {
-		const twips = Math.round(col.widthChars * 105);
+		const twips = Math.round(col.widthChars * 105 + 75);
 		for (let abs = col.min - 1; abs <= col.max - 1; abs++) {
 			const i = abs - colStart;
 			if (i >= 0 && i < colCount) columnWidths[i] = twips;
@@ -173,6 +257,7 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 	const scaled = printScale < .999;
 	const breakRows = new Set(worksheet.rowBreaks ?? []);
 	let textBudget = MAX_SHEET_TEXT_CHARS;
+	let textBudgetReported = false;
 	const runPropsByXf = /* @__PURE__ */ new Map();
 	const cellRunProps = (xf) => {
 		let props = runPropsByXf.get(xf);
@@ -200,7 +285,9 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 	for (let r = 0; r < rowCount; r++) {
 		const absR = r + rowStart;
 		const cells = [];
+		const overflowed = /* @__PURE__ */ new Set();
 		for (let c = 0; c < colCount; c++) {
+			if (overflowed.has(c)) continue;
 			const absC = c + colStart;
 			const merge = mergeOrigins.get(key(absR, absC));
 			if (insideMerge.has(key(absR, absC)) && !merge) {
@@ -211,11 +298,22 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 			const ws = cellMatrix[r]?.[c];
 			let text = ws ? resolveCellText(ws, sharedStrings, styles, date1904) : "";
 			const cfText = text.length > 0 ? text : void 0;
-			if (text.length > textBudget) text = text.slice(0, Math.max(0, textBudget));
+			if (text.length > textBudget) {
+				text = text.slice(0, Math.max(0, textBudget));
+				if (!textBudgetReported) {
+					textBudgetReported = true;
+					print.losses?.push({
+						severity: "dropped",
+						feature: FEATURES.text,
+						detail: `per-sheet text budget of ${MAX_SHEET_TEXT_CHARS} characters exhausted; the remaining cells render empty`,
+						...print.sheetName ? { where: `sheet "${print.sheetName}"` } : {}
+					});
+				}
+			}
 			textBudget -= text.length;
 			const xf = ws && ws.styleIndex !== void 0 ? styles.cellXfs[ws.styleIndex] : void 0;
 			let runProps = cellRunProps(xf);
-			const alignment = xf ? alignmentFromXf(xf) : void 0;
+			const alignment = alignmentFromXf(xf, ws?.type);
 			let shading = xf ? shadingFromXf(xf, styles) : void 0;
 			const tableFmt = tableFormatByCell.get(key(absR, absC));
 			if (!shading && tableFmt?.shading) shading = tableFmt.shading;
@@ -236,14 +334,16 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 					runProps = applyCfOverride(runProps, over);
 				}
 			}
+			let overflowSpan = 1;
 			const wrapText = xf?.alignment?.wrapText === true;
 			const rotation = xf?.alignment?.textRotation;
 			const rotated = rotation !== void 0 && rotation !== 0 && text.length > 0;
 			const shrinkToFit = xf?.alignment?.shrinkToFit === true && !wrapText && !rotated;
-			if (text.length > 0 && !merge && !wrapText && !rotated && !shrinkToFit && ws && (ws.type === "s" || ws.type === "str" || ws.type === "inlineStr") && (alignment === void 0 || alignment === "left")) {
+			if (text.length > 0 && !merge && !wrapText && !rotated && !shrinkToFit && ws && (ws.type === "s" || ws.type === "str" || ws.type === "inlineStr") && alignment === "left") {
 				let availTwips = columnWidths[c];
 				let cc = c + 1;
-				while (cc < colCount && !cellHasContent(cellMatrix[r]?.[cc])) {
+				const neighbourIsFree = (col) => !cellHasContent(cellMatrix[r]?.[col]) && !cellPaintsSomething(cellMatrix[r]?.[col], styles) && !sparklineByCell.has(key(absR, col + colStart)) && !(dropdownRanges.length > 0 && rangesCover(dropdownRanges, absR, col + colStart));
+				while (cc < colCount && neighbourIsFree(cc)) {
 					availTwips += columnWidths[cc];
 					cc++;
 				}
@@ -251,6 +351,10 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 					const charsFit = Math.max(1, Math.round(availTwips / 105));
 					if (text.length > charsFit) text = text.slice(0, charsFit);
 				}
+				if (cc > c + 1) {
+					overflowSpan = cc - c;
+					for (let k = c + 1; k < cc; k++) overflowed.add(k);
+				}
 			}
 			if (shrinkToFit && ws && text.length > 0) {
 				const charsFit = Math.max(1, columnWidths[c] / 105);
@@ -267,7 +371,7 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 			const href = print.hyperlinks && print.hyperlinks.length > 0 ? hyperlinkUrlAt(print.hyperlinks, absR, absC) : void 0;
 			const visibleEndCol = merge ? Math.min(merge.endColumn, colWindowEnd) : 0;
 			const properties = {
-				...merge && visibleEndCol > merge.startColumn ? { colSpan: visibleEndCol - merge.startColumn + 1 } : {},
+				...merge && visibleEndCol > merge.startColumn ? { colSpan: visibleEndCol - merge.startColumn + 1 } : overflowSpan > 1 ? { colSpan: overflowSpan } : {},
 				...merge && Math.min(merge.endRow, rowWindowEnd) > merge.startRow ? { merge: "start" } : {},
 				...shading ? { shading } : {},
 				...dataBar ? { dataBar } : {},
@@ -292,7 +396,7 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 				properties: runProps,
 				...href ? { href } : {}
 			}] : [];
-			const content = rotated ? stackedVerticalContent(text, runProps, href) : [{
+			const content = rotated ? stackedVerticalContent(text, runProps, href) : cellRuns.length === 0 ? [] : [{
 				kind: "paragraph",
 				paragraph: {
 					properties: paragraphProps,
@@ -326,6 +430,13 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 	};
 	const centered = worksheet.printOptions?.horizontalCentered === true;
 	const tableProperties = {
+		defaultCellMargins: {
+			left: pt(EXCEL_CELL_INSET_PT),
+			right: pt(EXCEL_CELL_INSET_PT),
+			top: pt(0),
+			bottom: pt(0)
+		},
+		layout: "fixed",
 		...print.gridLines ? { borders: {
 			top: thin,
 			bottom: thin,
@@ -360,7 +471,7 @@ function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 				...tableProperties,
 				frozen
 			} : tableProperties,
-			grid: columnWidths.map((w) => twipsToPt(w)),
+			grid: bandWidths.map((w) => twipsToPt(w)),
 			rows
 		}
 	}];
@@ -384,6 +495,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") {
@@ -440,10 +562,29 @@ function applyCfOverride(base, o) {
 		...o.italic !== void 0 ? { italic: o.italic } : {}
 	};
 }
-function alignmentFromXf(xf) {
-	const align = xf.alignment;
-	if (!align) return void 0;
-	return mapAlignment(align.horizontal);
+/**
+* ECMA-376 §18.8.1 — a cell's horizontal alignment, falling back to `general`.
+*
+* "General" is not "left": it is decided by the VALUE. Numbers, dates and times
+* go right, booleans and errors centre, text goes left. Treating an absent
+* `<alignment>` as no alignment at all left every number hugging the left edge
+* of its column, tens of points from where Excel and LibreOffice put it — on
+* the sheets where it matters most, since a column of figures is the common
+* case.
+*/
+function alignmentFromXf(xf, type) {
+	const explicit = xf?.alignment ? mapAlignment(xf.alignment.horizontal) : void 0;
+	if (explicit) return explicit;
+	return generalAlignment(type);
+}
+function generalAlignment(type) {
+	switch (type) {
+		case "n":
+		case "d": return "right";
+		case "b":
+		case "e": return "center";
+		default: return "left";
+	}
 }
 function mapAlignment(h) {
 	if (!h) return void 0;
@@ -603,7 +744,7 @@ function buildSparklineLookup(worksheet, print) {
 		const host = parseAreaRef(sp.sqref);
 		const area = parseAreaRef(sp.dataRange);
 		if (!host || !area) continue;
-		const values = collectSeriesValues(resolveSeriesGrid(sp.dataRange, worksheet, print.sheetGrids).cells, area);
+		const values = collectSeriesValues(resolveSeriesGrid(sp.dataRange, worksheet, print.sheetGrids).cells, area, print);
 		if (values.length === 0 || values.every((v) => v === null)) continue;
 		out.set(key(host.startRow, host.startColumn), {
 			kind: sp.kind,
@@ -623,7 +764,7 @@ function resolveSeriesGrid(dataRange, current, sheetGrids) {
 	return sheetGrids.get(name) ?? current;
 }
 var MAX_SPARKLINE_POINTS = 1e3;
-function collectSeriesValues(cells, area) {
+function collectSeriesValues(cells, area, print) {
 	const byKey = /* @__PURE__ */ new Map();
 	for (const c of cells) {
 		if (c.row < area.startRow || c.row > area.endRow) continue;
@@ -632,7 +773,14 @@ function collectSeriesValues(cells, area) {
 		const v = Number(c.rawValue);
 		if (Number.isFinite(v)) byKey.set(key(c.row, c.column), v);
 	}
-	if ((area.endRow - area.startRow + 1) * (area.endColumn - area.startColumn + 1) > MAX_SPARKLINE_POINTS) {
+	const cellCount = (area.endRow - area.startRow + 1) * (area.endColumn - area.startColumn + 1);
+	if (cellCount > MAX_SPARKLINE_POINTS) {
+		print.losses?.push({
+			severity: "degraded",
+			feature: FEATURES.charts,
+			detail: `sparkline range spans ${cellCount} cells (over ${MAX_SPARKLINE_POINTS}); plotted as the compact populated series, so blank gaps no longer hold their x-positions`,
+			...print.sheetName ? { where: `sheet "${print.sheetName}"` } : {}
+		});
 		const pts = [...byKey.entries()].map(([k, v]) => {
 			const [r, col] = k.split(",").map(Number);
 			return {
@@ -695,9 +843,65 @@ function buildTableFormatLookup(worksheet) {
 function cellHasContent(cell) {
 	return !!cell && (cell.rawValue !== "" || cell.inlineText !== void 0);
 }
+/**
+* The window-local index of the last row inside `[rowStart, rowStart+rowCount)`
+* that carries anything — a value, or a merge reaching into the window. `-1`
+* when the window is entirely blank.
+*/
+function lastContentRow(worksheet, rowStart, rowCount, colStart, colCount) {
+	const rowEnd = rowStart + rowCount - 1;
+	const colEnd = colStart + colCount - 1;
+	let last = -1;
+	for (const c of worksheet.cells) {
+		if (!cellHasContent(c)) continue;
+		if (c.row < rowStart || c.row > rowEnd || c.column < colStart || c.column > colEnd) continue;
+		if (c.row - rowStart > last) last = c.row - rowStart;
+	}
+	for (const m of worksheet.merges) {
+		if (m.startColumn > colEnd || m.endColumn < colStart) continue;
+		const reach = Math.min(m.endRow, rowEnd) - rowStart;
+		if (reach > last) last = reach;
+	}
+	return last;
+}
+/** The column twin of {@link lastContentRow}. */
+function lastContentColumn(worksheet, rowStart, rowCount, colStart, colCount) {
+	const rowEnd = rowStart + rowCount - 1;
+	const colEnd = colStart + colCount - 1;
+	let last = -1;
+	for (const c of worksheet.cells) {
+		if (!cellHasContent(c)) continue;
+		if (c.row < rowStart || c.row > rowEnd || c.column < colStart || c.column > colEnd) continue;
+		if (c.column - colStart > last) last = c.column - colStart;
+	}
+	for (const m of worksheet.merges) {
+		if (m.startRow > rowEnd || m.endRow < rowStart) continue;
+		const reach = Math.min(m.endColumn, colEnd) - colStart;
+		if (reach > last) last = reach;
+	}
+	return last;
+}
+/**
+* Whether an EMPTY cell still draws something of its own — a fill or a border.
+*
+* Such a cell cannot be swallowed by a neighbour's overflowing text: the span
+* that gives the text its width would take the paint with it.
+*/
+function cellPaintsSomething(cell, styles) {
+	if (!cell || cell.styleIndex === void 0) return false;
+	const xf = styles.cellXfs[cell.styleIndex];
+	if (!xf) return false;
+	return shadingFromXf(xf, styles) !== void 0 || bordersFromXf(xf, styles) !== void 0;
+}
 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,35 @@
 import { FlowDoc } from '../core/ir/flow.js';
+import { Loss } from '../core/ir/loss.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;
+    /**
+     * Sink the projection writes its {@link Loss} entries into — the print
+     * model's defence-in-depth caps (grid size, per-sheet text budget, sparkline
+     * range) fire on pathological input, and a cap that fires without saying so
+     * is a silent wrongness. {@link readXlsx} always supplies one and returns it
+     * as the read result's loss report; omitted ⇒ the caps still apply but go
+     * unreported.
+     */
+    readonly losses?: Array<Loss>;
 }
+/**
+ * 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;