reamkit 1.15.4 → 1.16.0

package/dist/esm/excel/column-bands.js

@@ -1,5 +1,74 @@
 import { twipsToPt } from "../core/ir/units.js";
 //#region src/excel/column-bands.ts
+/** §18.3.1.70 — the width of the row-number column, in twips. */
+var HEADING_COL_TWIPS = 460;
+/** The A1-style letters of an absolute column index (0 → A, 26 → AA). */
+function columnLetters(index) {
+	let n = index;
+	let out = "";
+	do {
+		out = String.fromCharCode(65 + n % 26) + out;
+		n = Math.floor(n / 26) - 1;
+	} while (n >= 0);
+	return out;
+}
+/**
+* Wrap a grid in its printed row and column headings (§18.3.1.70 `headings`):
+* the column letters across the top, the row numbers down the left, each in a
+* thin box, the way the sheet looks on screen. A banded sheet gets its own
+* letters per band, which is what both references print.
+*
+* @param rows       The band's rows.
+* @param widths     The band's column widths in twips.
+* @param colStart   The absolute index of the band's first column.
+* @param rowNumbers The absolute 1-based row number of each row.
+* @returns The rows and widths with the heading band added.
+*/
+function withHeadingBand(rows, widths, colStart, rowNumbers) {
+	const border = {
+		style: "single",
+		width: .5,
+		colorHex: "808080"
+	};
+	const borders = {
+		top: border,
+		bottom: border,
+		left: border,
+		right: border
+	};
+	const head = (text) => ({
+		properties: {
+			borders,
+			verticalAlign: "center"
+		},
+		content: [{
+			kind: "paragraph",
+			paragraph: {
+				properties: { alignment: "center" },
+				runs: [{
+					text,
+					properties: {}
+				}]
+			}
+		}]
+	});
+	const letters = [head("")];
+	for (let i = 0; i < widths.length; i++) letters.push(head(columnLetters(colStart + i)));
+	const out = [{
+		properties: { isHeader: true },
+		cells: letters
+	}];
+	rows.forEach((row, i) => {
+		out.push({
+			properties: row.properties,
+			cells: [head(String(rowNumbers[i] ?? i + 1)), ...row.cells]
+		});
+	});
+	return {
+		rows: out,
+		widths: [HEADING_COL_TWIPS, ...widths]
+	};
+}
 /**
 * Greedy fill: accumulate column widths until the next column would overflow the
 * content width, then start a new band. A manual column break (`colBreaks` holds
@@ -50,27 +119,63 @@ function computeColumnBands(columnWidths, contentWidthTwips, colBreaks) {
 * @param columnWidths Per-column widths in twips, by local index.
 * @param bands        The bands from {@link computeColumnBands}.
 * @param properties   The shared table properties applied to every band.
+* @param titleRowIndex The print-title row, or -1.
+* @param drawingReachTwips How far right the sheet's drawings reach (0 if none).
+* @param headings §18.3.1.70 — the printed row/column headings, when the sheet
+*   asks for them: the absolute index of the grid's first column and the sheet
+*   row number of each emitted row. Each band gets ITS OWN letters, which is
+*   what both references print across the top of a continuation page.
 * @returns One table body element per band, in band order.
 */
-function bandedTables(rows, columnWidths, bands, properties) {
-	return bands.map((band, bandIndex) => {
-		return {
-			kind: "table",
-			table: {
-				properties,
-				grid: columnWidths.slice(band.start, band.end + 1).map((w) => twipsToPt(w)),
-				rows: rows.map((row, rowIndex) => {
-					const cells = sliceRowCells(row.cells, band);
-					return {
-						properties: bandIndex > 0 && rowIndex === 0 ? {
-							...row.properties,
-							pageBreakBefore: true
-						} : row.properties,
-						cells
-					};
-				})
-			}
-		};
+function bandedTables(rows, columnWidths, bands, properties, titleRowIndex = -1, drawingReachTwips = 0, headings) {
+	return bands.flatMap((band, bandIndex) => {
+		const bandLeft = columnWidths.slice(0, band.start).reduce((sum, w) => sum + w, 0);
+		const bandTwips = columnWidths.slice(band.start, band.end + 1);
+		const grid = bandTwips.map((w) => twipsToPt(w));
+		const bandRowNumbers = [...headings?.rowNumbers ?? []];
+		const bandRows = rows.map((row, rowIndex) => {
+			const cells = sliceRowCells(row.cells, band);
+			return {
+				properties: bandIndex > 0 && rowIndex === 0 ? {
+					...row.properties,
+					pageBreakBefore: true
+				} : row.properties,
+				cells
+			};
+		});
+		if (bandIndex > 0 && !(bandLeft < drawingReachTwips) && !bandRows.some(rowDrawsSomething)) return [];
+		while (bandRows.length > 1 && !rowDrawsSomething(bandRows[bandRows.length - 1])) {
+			bandRows.pop();
+			bandRowNumbers.pop();
+		}
+		return (titleRowIndex > 0 && titleRowIndex < bandRows.length ? [{
+			rows: bandRows.slice(0, titleRowIndex),
+			numbers: bandRowNumbers.slice(0, titleRowIndex)
+		}, {
+			rows: bandRows.slice(titleRowIndex),
+			numbers: bandRowNumbers.slice(titleRowIndex)
+		}] : [{
+			rows: bandRows,
+			numbers: bandRowNumbers
+		}]).map((part) => {
+			const headed = headings ? withHeadingBand(part.rows, bandTwips, headings.colStart + band.start, part.numbers) : void 0;
+			return {
+				kind: "table",
+				table: {
+					properties,
+					grid: headed ? headed.widths.map((w) => twipsToPt(w)) : grid,
+					rows: headed ? leadWithBandBreak(headed.rows) : part.rows
+				}
+			};
+		});
+	});
+}
+/** Whether a row would put anything on the page — content, fill, border or mark. */
+function rowDrawsSomething(row) {
+	return row.cells.some((cell) => {
+		if (cell.content.length > 0) return true;
+		const p = cell.properties;
+		return p.shading !== void 0 || p.borders !== void 0 || p.dataBar !== void 0 || p.icon !== void 0 || p.sparkline !== void 0 || p.dropdown === true;
 	});
 }
 function sliceRowCells(cells, band) {
@@ -103,5 +208,36 @@ function blankCell(span) {
 		content: []
 	};
 }
+/**
+* Move a `pageBreakBefore` that landed on the second row up to the first.
+*
+* The band's page break is set on the band's own leading row, before the
+* heading band prepends the column-letter row in front of it. Left there, the
+* letters print on one page and the band they label starts on the next.
+*
+* @param rows The band's rows, letters row first.
+* @returns The same rows with the break carried by whichever leads them.
+*/
+function leadWithBandBreak(rows) {
+	const second = rows[1];
+	if (!second?.properties.pageBreakBefore) return rows;
+	const [first, ...rest] = rows;
+	if (!first) return rows;
+	const { pageBreakBefore: _dropped, ...keep } = second.properties;
+	return [
+		{
+			...first,
+			properties: {
+				...first.properties,
+				pageBreakBefore: true
+			}
+		},
+		{
+			...second,
+			properties: keep
+		},
+		...rest.slice(1)
+	];
+}
 //#endregion
-export { bandedTables, computeColumnBands };
+export { bandedTables, computeColumnBands, withHeadingBand };

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

@@ -1,7 +1,9 @@
+import { resolveInternalEntities } from "../core/opc/xml-entities.js";
 import { XMLParser } from "fast-xml-parser";
 //#region src/excel/comments-parser.ts
 var decoder = new TextDecoder("utf-8");
 var parser = new XMLParser({
+	htmlEntities: true,
 	ignoreAttributes: false,
 	attributeNamePrefix: "@_",
 	textNodeName: "#text",
@@ -17,7 +19,7 @@ var parser = new XMLParser({
 * of the text — stripped here so the resolved author is not shown twice.
 */
 function parseLegacyComments(data) {
-	const root = asObject(parser.parse(decoder.decode(data))["comments"]);
+	const root = asObject(parser.parse(resolveInternalEntities(decoder.decode(data)))["comments"]);
 	if (!root) return [];
 	const authors = toArray(asObject(root["authors"])?.["author"]).map((a) => textOf(a));
 	const out = [];
@@ -44,7 +46,7 @@ function parseLegacyComments(data) {
 * the authors of threaded comments.
 */
 function parsePersons(data) {
-	const root = asObject(parser.parse(decoder.decode(data))["personList"]);
+	const root = asObject(parser.parse(resolveInternalEntities(decoder.decode(data)))["personList"]);
 	const map = /* @__PURE__ */ new Map();
 	if (!root) return map;
 	for (const p of toArray(root["person"])) {
@@ -65,7 +67,7 @@ function parsePersons(data) {
 * @param persons The `id → displayName` map from {@link parsePersons}.
 */
 function parseThreadedComments(data, persons) {
-	const root = asObject(parser.parse(decoder.decode(data))["ThreadedComments"]);
+	const root = asObject(parser.parse(resolveInternalEntities(decoder.decode(data)))["ThreadedComments"]);
 	if (!root) return [];
 	const out = [];
 	for (const c of toArray(root["threadedComment"])) {

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

@@ -1,5 +1,5 @@
 import { CellIcon } from '../core/document-model/index.js';
-import { ConditionalFormat, DefinedName, WorksheetCell, XlsxStyles } from '../core/spreadsheet-model/index.js';
+import { ConditionalFormat, DefinedName, WorksheetCell, XlsxBorder, XlsxStyles } from '../core/spreadsheet-model/index.js';
 /**
  * A resolved per-cell override the print model layers over a cell's base format: a
  * solid highlight fill, font tweaks, an in-cell data bar (fraction of the cell
@@ -7,16 +7,32 @@ import { ConditionalFormat, DefinedName, WorksheetCell, XlsxStyles } from '../co
  */
 export interface CfOverride {
     readonly fillHex?: string;
+    /**
+     * §18.8.9 — the edges the rule's dxf declares. A rule may format with nothing
+     * else, and dropping them made such a rule invisible.
+     */
+    readonly border?: XlsxBorder;
+    /** §18.8.9 — the format the rule renders the cell's value in. */
+    readonly numberFormat?: string;
     readonly fontColorHex?: string;
     readonly bold?: boolean;
     readonly italic?: boolean;
+    /** §18.8.37 — the rule strikes the cell's text through. */
+    readonly strike?: boolean;
     /** An in-cell data bar: its fraction of the cell width, colour, and optional left offset. */
     readonly dataBar?: {
         readonly fraction: number;
         readonly colorHex: string;
         readonly startFraction?: number;
+        readonly negative?: boolean;
     };
     readonly icon?: CellIcon;
+    /**
+     * §18.3.1.28 `<dataBar showValue="0">` — the cell shows its BAR and not its
+     * number. Excel's "Show Bar Only": the figure would otherwise sit on top of
+     * its own gauge.
+     */
+    readonly hideValue?: boolean;
 }
 /**
  * A per-cell lookup returning the {@link CfOverride} for the cell at `(row, col)`,
@@ -25,7 +41,14 @@ export interface CfOverride {
  * text tests and to key duplicate / unique comparisons for non-numeric cells
  * (empty/undefined for a blank cell).
  */
-export type CellConditionalFormatter = (row: number, col: number, numericValue: number | undefined, text: string | undefined) => CfOverride | undefined;
+export type CellConditionalFormatter = (row: number, col: number, numericValue: number | undefined, text: string | undefined, 
+/**
+ * The cell holds nothing. It still COMPARES as zero — Excel and Calc both
+ * colour an empty cell for a rule written `cellIs equal 0`, which is how
+ * 48539.xlsx paints its whole Pass/Fail column red — but it is not a value
+ * that can repeat, so duplicate/uniqueValues must pass it over.
+ */
+blank?: boolean) => CfOverride | undefined;
 /**
  * Compile a sheet's `<conditionalFormatting>` rules + the workbook's `<dxfs>` into
  * a per-cell {@link CellConditionalFormatter}. Returns undefined when the sheet has

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

@@ -89,22 +89,24 @@ function buildConditionalFormatter(conditionalFormats, styles, cells, resolveTex
 		definedNames: definedNames ?? []
 	} : void 0;
 	const ctx = hasExpr ? buildEvalContext(cells, resolveText, nowSerial, date1904, cross) : void 0;
-	return (row, col, value, text) => {
+	return (row, col, value, text, blank) => {
 		if (!hasExpr && value === void 0 && (text === void 0 || text.length === 0)) return;
-		const dupKey = dupKeyOf(value, text);
+		const dupKey = blank === true ? void 0 : dupKeyOf(value, text);
 		let textFmt;
 		let textClaimed = false;
 		let bar;
+		let hideValue = false;
 		let icon;
-		const claim = (dxfId) => {
-			textFmt = dxfToOverride(dxfs[dxfId]);
+		const claim = (r) => {
+			textFmt = dxfToOverride(r.dxf ?? dxfs[r.dxfId]);
 			textClaimed = true;
 		};
 		for (const { ranges, rule, scale, bar: resolved, iconThresholds, threshold, dupKeys, compiled, origin } of flat) {
 			if (!coversCell(ranges, row, col)) continue;
 			switch (rule.type) {
 				case "cellIs":
-					if (!textClaimed && value !== void 0 && cellIsMatches(rule.operator, value, rule.formulas)) claim(rule.dxfId);
+					if (textClaimed) break;
+					if (value !== void 0 && Number.isFinite(Number(operandText(rule.formulas[0]))) ? cellIsMatches(rule.operator, value, rule.formulas) : text !== void 0 && cellIsMatchesText(rule.operator, text, rule.formulas)) claim(rule);
 					break;
 				case "colorScale":
 					if (!textClaimed && value !== void 0 && scale) {
@@ -113,7 +115,10 @@ function buildConditionalFormatter(conditionalFormats, styles, cells, resolveTex
 					}
 					break;
 				case "dataBar":
-					if (!bar && value !== void 0 && resolved) bar = dataBarBar(resolved, value);
+					if (!bar && value !== void 0 && resolved) {
+						bar = dataBarBar(resolved, value);
+						if (rule.showValue === false) hideValue = true;
+					}
 					break;
 				case "iconSet":
 					if (!icon && value !== void 0 && iconThresholds) {
@@ -123,17 +128,17 @@ function buildConditionalFormatter(conditionalFormats, styles, cells, resolveTex
 					break;
 				case "top10":
 				case "aboveAverage":
-					if (!textClaimed && value !== void 0 && threshold && thresholdMatches(threshold, value)) claim(rule.dxfId);
+					if (!textClaimed && value !== void 0 && threshold && thresholdMatches(threshold, value)) claim(rule);
 					break;
 				case "duplicateValues":
 				case "uniqueValues":
-					if (!textClaimed && dupKey !== void 0 && dupKeys?.has(dupKey)) claim(rule.dxfId);
+					if (!textClaimed && dupKey !== void 0 && dupKeys?.has(dupKey)) claim(rule);
 					break;
 				case "containsText":
 				case "notContainsText":
 				case "beginsWith":
 				case "endsWith":
-					if (!textClaimed && text !== void 0 && textRuleMatches(rule, text)) claim(rule.dxfId);
+					if (!textClaimed && text !== void 0 && textRuleMatches(rule, text)) claim(rule);
 					break;
 				case "expression":
 					if (!textClaimed && compiled && ctx && origin) {
@@ -142,11 +147,11 @@ function buildConditionalFormatter(conditionalFormats, styles, cells, resolveTex
 							dCol: col - origin.col,
 							curRow: row,
 							curCol: col
-						})) claim(rule.dxfId);
+						})) claim(rule);
 					}
 					break;
 				case "timePeriod":
-					if (!textClaimed && value !== void 0 && nowSerial !== void 0 && timePeriodMatches(rule.timePeriod, value, nowSerial, date1904)) claim(rule.dxfId);
+					if (!textClaimed && value !== void 0 && nowSerial !== void 0 && timePeriodMatches(rule.timePeriod, value, nowSerial, date1904)) claim(rule);
 					break;
 			}
 		}
@@ -154,7 +159,8 @@ function buildConditionalFormatter(conditionalFormats, styles, cells, resolveTex
 		return {
 			...textFmt ?? {},
 			...bar ? { dataBar: bar } : {},
-			...icon ? { icon } : {}
+			...icon ? { icon } : {},
+			...hideValue ? { hideValue: true } : {}
 		};
 	};
 }
@@ -277,6 +283,39 @@ function coversCell(ranges, row, col) {
 	for (const r of ranges) if (row >= r.startRow && row <= r.endRow && col >= r.startColumn && col <= r.endColumn) return true;
 	return false;
 }
+/** A `cellIs` operand: a bare number, or a quoted string literal. */
+function operandText(raw) {
+	const t = (raw ?? "").trim();
+	const quoted = /^"(.*)"$/su.exec(t);
+	return quoted ? quoted[1] ?? "" : t;
+}
+/**
+* §18.3.1.11 — a `cellIs` rule compares the cell against one or two operands,
+* and the comparison is not always arithmetic: `notEqual ""` over a sheet of
+* words is how a document asks to format every cell that HOLDS something.
+* Reading only numbers, that rule matched nothing, and
+* tdf152581_bordercolorNotExportedToXLSX.xlsx lost the border and fill its two
+* cells carry. Both sides numeric ⇒ compare numbers, as before; otherwise
+* compare text, case-insensitively, the way Excel collates it.
+*/
+function cellIsMatchesText(operator, text, formulas) {
+	const a = operandText(formulas[0]).toLowerCase();
+	const v = text.toLowerCase();
+	switch (operator) {
+		case "lessThan": return v < a;
+		case "lessThanOrEqual": return v <= a;
+		case "equal": return v === a;
+		case "notEqual": return v !== a;
+		case "greaterThanOrEqual": return v >= a;
+		case "greaterThan": return v > a;
+		case "between":
+		case "notBetween": {
+			const b = operandText(formulas[1]).toLowerCase();
+			const inside = v >= (a <= b ? a : b) && v <= (a <= b ? b : a);
+			return operator === "between" ? inside : !inside;
+		}
+	}
+}
 function cellIsMatches(operator, value, formulas) {
 	const a = Number(formulas[0]);
 	if (!Number.isFinite(a)) return false;
@@ -304,6 +343,9 @@ function dxfToOverride(dxf) {
 	if (dxf.font?.colorHex) out.fontColorHex = dxf.font.colorHex;
 	if (dxf.font?.bold !== void 0) out.bold = dxf.font.bold;
 	if (dxf.font?.italic !== void 0) out.italic = dxf.font.italic;
+	if (dxf.font?.strike !== void 0) out.strike = dxf.font.strike;
+	if (dxf.border) out.border = dxf.border;
+	if (dxf.numberFormat) out.numberFormat = dxf.numberFormat;
 	return Object.keys(out).length > 0 ? out : void 0;
 }
 function collectRangeValues(cells, ranges) {
@@ -323,8 +365,8 @@ function resolveColorScale(rule, ranges, cells) {
 	const vmin = sorted[0];
 	const vmax = sorted[sorted.length - 1];
 	const thresholds = [];
-	for (const cfvo of rule.cfvos) {
-		const t = resolveCfvo(cfvo, vmin, vmax, sorted);
+	for (const [i, cfvo] of rule.cfvos.entries()) {
+		const t = resolveCfvo(cfvo, vmin, vmax, sorted, i === rule.cfvos.length - 1);
 		if (t === void 0) return void 0;
 		thresholds.push(t);
 	}
@@ -341,16 +383,16 @@ function resolveColorScale(rule, ranges, cells) {
 		colors
 	};
 }
-function resolveCfvo(cfvo, vmin, vmax, sorted) {
+function resolveCfvo(cfvo, vmin, vmax, sorted, isLast = false) {
 	switch (cfvo.type) {
 		case "min":
 		case "autoMin": return vmin;
 		case "max":
 		case "autoMax": return vmax;
-		case "num":
+		case "num": return Number.isFinite(Number(cfvo.val)) ? Number(cfvo.val) : void 0;
 		case "formula": {
 			const n = Number(cfvo.val);
-			return Number.isFinite(n) ? n : void 0;
+			return Number.isFinite(n) ? n : isLast ? vmax : vmin;
 		}
 		case "percent": {
 			const p = Number(cfvo.val);
@@ -410,7 +452,7 @@ function resolveDataBar(rule, ranges, cells) {
 	const vmin = sorted[0];
 	const vmax = sorted[sorted.length - 1];
 	const lower = resolveCfvo(rule.cfvos[0], vmin, vmax, sorted);
-	const upper = resolveCfvo(rule.cfvos[1], vmin, vmax, sorted);
+	const upper = resolveCfvo(rule.cfvos[1], vmin, vmax, sorted, true);
 	if (lower === void 0 || upper === void 0) return void 0;
 	return {
 		lower,
@@ -433,7 +475,8 @@ function dataBarBar(bar, value) {
 		return {
 			fraction: w,
 			colorHex: bar.negativeColorHex,
-			startFraction: axis - w
+			startFraction: axis - w,
+			negative: true
 		};
 	}
 	return {
@@ -577,6 +620,7 @@ function resolveDupUnique(rule, ranges, cells, resolveText) {
 }
 function cellDupKey(cell, resolveText) {
 	if (cell.type === "n") {
+		if (cell.rawValue.length === 0) return void 0;
 		const n = Number(cell.rawValue);
 		return Number.isFinite(n) ? `n:${n}` : void 0;
 	}

package/dist/esm/excel/escaped-text.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Decode a SpreadsheetML `ST_Xstring` (§22.9.2.19): every `_xHHHH_` becomes the
+ * character it names. Text carrying no escape is returned unchanged, so the
+ * common path costs one failed match.
+ *
+ * @param text The raw `<t>` content.
+ * @returns The text with its escapes resolved.
+ */
+export declare function decodeXstring(text: string): string;

package/dist/esm/excel/escaped-text.js

@@ -0,0 +1,20 @@
+//#region src/excel/escaped-text.ts
+var ESCAPE = /_x([0-9A-Fa-f]{4})_/g;
+/**
+* Decode a SpreadsheetML `ST_Xstring` (§22.9.2.19): every `_xHHHH_` becomes the
+* character it names. Text carrying no escape is returned unchanged, so the
+* common path costs one failed match.
+*
+* @param text The raw `<t>` content.
+* @returns The text with its escapes resolved.
+*/
+function decodeXstring(text) {
+	if (!text.includes("_x")) return text;
+	return text.replace(ESCAPE, (whole, hex) => {
+		const code = Number.parseInt(hex, 16);
+		if (code >= 55296 && code <= 57343) return whole;
+		return String.fromCodePoint(code);
+	});
+}
+//#endregion
+export { decodeXstring };

package/dist/esm/excel/form-control-parser.js

@@ -2,6 +2,7 @@ import { XMLParser } from "fast-xml-parser";
 //#region src/excel/form-control-parser.ts
 var decoder = new TextDecoder("utf-8");
 var parser = new XMLParser({
+	htmlEntities: true,
 	ignoreAttributes: false,
 	attributeNamePrefix: "@_",
 	parseAttributeValue: false,

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

@@ -1,4 +1,4 @@
-import { excelSerialFromUtcParts, excelSerialToDate } from "../number-format.js";
+import { excelSerialFromUtcParts, excelSerialToDate } from "../../core/number-format.js";
 //#region src/excel/formula/dates.ts
 /**
 * Decompose an Excel serial into UTC calendar parts. A fractional serial is

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

@@ -7,5 +7,13 @@ import { BodyElement } from '../core/document-model/index.js';
  *
  * @param formatString The raw `&`-code format string.
  * @param sheetName    The worksheet tab name, substituted for `&A`.
+ * @param scale        The sheet's print scale.
+ * @param basePt       The default header font size.
+ * @param fileName     The workbook's file name, substituted for `&F`. A
+ *                     byte-oriented API does not know it, so the caller supplies
+ *                     it; absent, `&F` is dropped as before.
+ * @param themePalette The workbook theme, resolving a `&K` theme reference.
+ * @param now          The reference date `&D`/`&T` print. An explicit input,
+ *                     never the wall clock; absent, both are dropped as before.
  */
-export declare function buildHeaderFooterContent(formatString: string, sheetName: string): Array<BodyElement>;
+export declare function buildHeaderFooterContent(formatString: string, sheetName: string, scale?: number, basePt?: number, fileName?: string, themePalette?: ReadonlyMap<string, string>, now?: Date): Array<BodyElement>;