reamkit 1.15.4 → 1.17.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>;

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

@@ -1,4 +1,38 @@
+import { pt } from "../core/ir/units.js";
 //#region src/excel/header-footer.ts
+var HEADER_THEME_SLOTS = [
+	"lt1",
+	"dk1",
+	"lt2",
+	"dk2",
+	"accent1",
+	"accent2",
+	"accent3",
+	"accent4",
+	"accent5",
+	"accent6",
+	"hlink",
+	"folHlink"
+];
+/**
+* Lighten or darken a theme colour by a header/footer tint (§18.3.1.55): the
+* value is a fraction of the way to white, or to black when the sign is minus.
+*
+* @param hex     The theme colour, RRGGBB.
+* @param amount  0..1.
+* @param darken  True for a `-` sign.
+* @returns The tinted colour, RRGGBB.
+*/
+function applyHeaderTint(hex, amount, darken) {
+	if (!(amount > 0)) return hex.toUpperCase();
+	const n = parseInt(hex, 16);
+	const mix = (c) => darken ? Math.round(c * (1 - amount)) : Math.round(c + (255 - c) * amount);
+	return [
+		mix(n >> 16 & 255),
+		mix(n >> 8 & 255),
+		mix(n & 255)
+	].map((c) => c.toString(16).padStart(2, "0")).join("").toUpperCase();
+}
 /**
 * 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 `[]`
@@ -7,16 +41,24 @@
 *
 * @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.
 */
-function buildHeaderFooterContent(formatString, sheetName) {
-	const regions = parseHeaderFooterString(formatString, sheetName);
+function buildHeaderFooterContent(formatString, sheetName, scale = 1, basePt = DEFAULT_HEADER_PT, fileName, themePalette, now) {
+	const regions = parseHeaderFooterString(formatString, sheetName, scale, basePt, fileName, themePalette, now);
 	const out = [];
 	const para = (runs, alignment) => {
-		if (runs.length > 0) out.push({
+		for (const line of splitLines(runs)) if (line.length > 0) out.push({
 			kind: "paragraph",
 			paragraph: {
 				properties: { alignment },
-				runs: [...runs]
+				runs: line
 			}
 		});
 	};
@@ -25,7 +67,34 @@ function buildHeaderFooterContent(formatString, sheetName) {
 	para(regions.right, "right");
 	return out;
 }
-function parseHeaderFooterString(s, sheetName) {
+/**
+* Break a region's runs at the line breaks Excel allows inside one — a header
+* region is not necessarily one line.
+*
+* The break is a literal CR/LF in the format string, not a `&`-code, so it
+* arrives as text. Left as text it is drawn: tdf58243.xlsx puts a CR LF in the
+* middle of its centre header and we rendered the carriage return as a missing
+* glyph — a tofu box mid-title — with the rest of the title running on after it
+* where every other reader starts a second line.
+*/
+function splitLines(runs) {
+	const lines = [[]];
+	for (const run of runs) {
+		const parts = run.text.split(/\r\n|\r|\n/);
+		for (let i = 0; i < parts.length; i++) {
+			if (i > 0) lines.push([]);
+			const text = parts[i];
+			if (text.length > 0) lines[lines.length - 1].push({
+				...run,
+				text
+			});
+		}
+	}
+	return lines;
+}
+/** The point size a header run takes when it names none — the layout's own. */
+var DEFAULT_HEADER_PT = 11;
+function parseHeaderFooterString(s, sheetName, scale, basePt, fileName, themePalette, now) {
 	const regions = {
 		left: [],
 		center: [],
@@ -34,11 +103,22 @@ function parseHeaderFooterString(s, sheetName) {
 	let current = regions.center;
 	let bold = false;
 	let italic = false;
+	let underline = false;
+	let strike = false;
+	let sizePt;
+	let colorHex;
 	let buf = "";
-	const runProps = () => ({
-		...bold ? { bold: true } : {},
-		...italic ? { italic: true } : {}
-	});
+	const runProps = () => {
+		const effectivePt = (sizePt ?? basePt) * scale;
+		return {
+			...bold ? { bold: true } : {},
+			...italic ? { italic: true } : {},
+			...underline ? { underline: "single" } : {},
+			...strike ? { strike: true } : {},
+			...effectivePt !== DEFAULT_HEADER_PT ? { fontSizePt: pt(effectivePt) } : {},
+			...colorHex !== void 0 ? { colorHex } : {}
+		};
+	};
 	const flush = () => {
 		if (buf.length > 0) {
 			current.push({
@@ -77,6 +157,12 @@ function parseHeaderFooterString(s, sheetName) {
 		if (next === "L" || next === "C" || next === "R") {
 			flush();
 			current = next === "L" ? regions.left : next === "R" ? regions.right : regions.center;
+			bold = false;
+			italic = false;
+			underline = false;
+			strike = false;
+			sizePt = void 0;
+			colorHex = void 0;
 			i += 2;
 			continue;
 		}
@@ -107,24 +193,78 @@ function parseHeaderFooterString(s, sheetName) {
 			i += 2;
 			continue;
 		}
+		if (next === "U") {
+			flush();
+			underline = !underline;
+			i += 2;
+			continue;
+		}
+		if (next === "S") {
+			flush();
+			strike = !strike;
+			i += 2;
+			continue;
+		}
 		if (next === "K") {
 			i += 2;
-			let n = 0;
-			while (n < 6 && i < s.length && /[0-9A-Fa-f]/.test(s[i])) {
+			const themed = /^(\d\d)([+-])(\d\d\d)/.exec(s.slice(i));
+			if (themed) {
+				i += themed[0].length;
+				const slot = HEADER_THEME_SLOTS[Number(themed[1])];
+				const base = slot ? themePalette?.get(slot) : void 0;
+				flush();
+				colorHex = base ? applyHeaderTint(base, Number(themed[3]) / 1e3, themed[2] === "-") : void 0;
+				continue;
+			}
+			let hex = "";
+			while (hex.length < 6 && i < s.length && /[0-9A-Fa-f]/.test(s[i])) {
+				hex += s[i];
 				i++;
-				n++;
+			}
+			if (hex.length === 6) {
+				flush();
+				colorHex = hex.toUpperCase();
 			}
 			continue;
 		}
 		if (next === "\"") {
 			i += 2;
-			while (i < s.length && s[i] !== "\"") i++;
+			let spec = "";
+			while (i < s.length && s[i] !== "\"") {
+				spec += s[i];
+				i++;
+			}
 			if (i < s.length) i++;
+			const style = (spec.split(",")[1] ?? "").toLowerCase();
+			if (style.length > 0) {
+				flush();
+				bold = style.includes("bold");
+				italic = style.includes("italic") || style.includes("oblique");
+			}
 			continue;
 		}
 		if (next >= "0" && next <= "9") {
 			i += 1;
-			while (i < s.length && s[i] >= "0" && s[i] <= "9") i++;
+			let digits = "";
+			while (i < s.length && s[i] >= "0" && s[i] <= "9") {
+				digits += s[i];
+				i++;
+			}
+			const n = Number(digits);
+			if (Number.isFinite(n) && n > 0 && n <= 409) {
+				flush();
+				sizePt = n;
+			}
+			continue;
+		}
+		if (next === "F") {
+			if (fileName !== void 0 && fileName.length > 0) buf += fileName;
+			i += 2;
+			continue;
+		}
+		if ((next === "D" || next === "T") && now) {
+			buf += next === "D" ? shortDate(now) : clockTime(now);
+			i += 2;
 			continue;
 		}
 		i += 2;
@@ -132,5 +272,13 @@ function parseHeaderFooterString(s, sheetName) {
 	flush();
 	return regions;
 }
+function shortDate(d) {
+	const p = (n) => String(n).padStart(2, "0");
+	return `${p(d.getUTCMonth() + 1)}/${p(d.getUTCDate())}/${String(d.getUTCFullYear())}`;
+}
+function clockTime(d) {
+	const p = (n) => String(n).padStart(2, "0");
+	return `${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())}`;
+}
 //#endregion
 export { buildHeaderFooterContent };

package/dist/esm/excel/index.d.ts

@@ -10,4 +10,4 @@ export { parseWorksheet } from './worksheet-parser.js';
 export type { CellType, ColumnWidth, DataValidation, DataValidationType, HeaderFooter, HyperlinkRef, ExcelTable, MergedRange, ParsedWorksheet, RowHeight, SheetRichRun, WorksheetCell, XlsxPageMargins, XlsxPageSetup, XlsxPrintOptions, } from '../core/spreadsheet-model/index.js';
 export { parseXlsxStyles, EMPTY_XLSX_STYLES } from './styles-parser.js';
 export type { XlsxBorder, XlsxBorderEdge, XlsxBorderStyleName, XlsxCellAlignment, XlsxCellXf, XlsxFill, XlsxFont, XlsxHorizontalAlign, XlsxStyles, XlsxVerticalAlign, } from '../core/spreadsheet-model/index.js';
-export { applyNumberFormat } from './number-format.js';
+export { applyNumberFormat, generalToWidth, numberFormatColorHex } from '../core/number-format.js';

package/dist/esm/excel/index.js

@@ -1,7 +1,7 @@
+import "../core/number-format.js";
 import "./cell-reference.js";
 import "./defined-name-ref.js";
 import "./shared-strings-parser.js";
 import "./workbook-parser.js";
-import "./worksheet-parser.js";
 import "./styles-parser.js";
-import "./number-format.js";
+import "./worksheet-parser.js";

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

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

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

@@ -20,11 +20,36 @@ export declare const TWIPS_PER_EXCEL_CHAR = 105;
  * default was derived from the full formula while the explicit path dropped it.
  */
 export declare const COL_PADDING_TWIPS = 75;
+/**
+ * §18.3.1.13 — a `<col width>` in twips.
+ *
+ * The padding above is the formula for a column at least one character wide.
+ * Excel documents a SEPARATE one below that: `px = Trunc(width × MDW + 0.5)`,
+ * with no padding at all. It matters because the padding is a constant: on a
+ * form drawn over a fine grid — tdf118668.xlsx rules 168 columns of 0.855
+ * characters — 3.75pt of padding nearly doubles a 4.5pt column, and the sheet
+ * came out 1384pt wide against the reference's 754, so it paginated across two
+ * pages where every reader prints one.
+ *
+ * @param chars     The declared width in characters.
+ * @param charTwips The Maximum Digit Width, in twips.
+ * @returns The rendered column width in twips.
+ */
+export declare function columnTwips(chars: number, charTwips: number): number;
 /**
  * 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;
+/**
+ * The row height a sheet that declares none inherits from the workbook's
+ * Normal font. Sizes outside Excel's table scale from its 10pt entry and snap
+ * up to the 0.75pt grid row heights are stored on (one pixel at 96 dpi).
+ *
+ * @param fontPt The Normal style's font size, or undefined if unknown.
+ * @returns The default row height in points.
+ */
+export declare function defaultRowHeightPtFor(fontPt: number | undefined): number;
 /**
  * Excel's default row height is ~15pt = 300 twips. Used (for the `fitToHeight`
  * estimate) for rows without an explicit `<row ht="..">`.
@@ -52,6 +77,22 @@ export declare function resolvePrintTitleRows(definedNames: ReadonlyArray<Define
     readonly startRow: number;
     readonly endRow: number;
 } | undefined;
+/**
+ * The width one page has for content: the sheet's paper (declared or the A4
+ * default) less its left and right margins, in points. The same measure the
+ * column bands are packed into — a drawing layer banded on any other width
+ * would not line up with the grid beside it.
+ */
+export declare function printableWidthPt(worksheet: ParsedWorksheet): number;
+/**
+ * The printable HEIGHT of one page of this sheet, in points — its paper height
+ * less its own top and bottom margins. The vertical twin of
+ * {@link printableWidthPt}.
+ *
+ * @param worksheet The parsed worksheet (paper + margins).
+ * @returns The height a page of this sheet has for content, in points.
+ */
+export declare function printableHeightPt(worksheet: ParsedWorksheet): number;
 interface PrintModelOptions {
     readonly printArea?: CellRange;
     readonly gridLines: boolean;
@@ -65,6 +106,18 @@ interface PrintModelOptions {
     readonly hyperlinks?: ReadonlyArray<SheetHyperlink>;
     readonly sharedStringRuns?: ReadonlyArray<ReadonlyArray<SheetRichRun> | undefined>;
     readonly now?: Date;
+    readonly digitWidthPt?: number;
+    readonly defaultFontPt?: number;
+    readonly scaleSink?: {
+        value: number;
+    };
+    readonly bandSink?: {
+        lefts: Array<number>;
+    };
+    readonly drawingExtentPt?: {
+        readonly widthPt: number;
+        readonly heightPt: number;
+    };
     readonly losses?: Array<Loss>;
 }
 /**
@@ -96,6 +149,28 @@ export declare function worksheetToBody(worksheet: ParsedWorksheet, sharedString
  * @returns The resolved display string.
  */
 export declare function resolveCellText(cell: WorksheetCell, sharedStrings: ReadonlyArray<string>, styles: XlsxStyles, date1904: boolean): string;
+/**
+ * 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.
+ */
+/**
+ * Whether a cell puts anything VISIBLE on an otherwise-empty page.
+ *
+ * The difference from {@link cellPaintsSomething} is white: a solid fill in the
+ * paper's own colour paints nothing a reader can see, and a sheet of them is a
+ * blank sheet. bnc762542.xlsx is 176 such cells — `fgColor indexed="9"`, the
+ * legacy palette's white — with every word it prints living in a callout, and
+ * both references print the callout on a bare page. 48779.xlsx is one cell of
+ * solid red, and both print the swatch.
+ *
+ * @param cell   The cell, or undefined.
+ * @param styles The workbook's style tables.
+ * @returns True when the cell draws something the eye can find.
+ */
+export declare function cellPaintsVisibly(cell: WorksheetCell | undefined, styles: XlsxStyles): boolean;
+export declare function cellPaintsSomething(cell: WorksheetCell | undefined, styles: XlsxStyles): boolean;
 /**
  * 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