reamkit 1.31.0 → 1.32.0

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

@@ -17,3 +17,12 @@ export interface SharedStrings {
  * cell limit (32 767 chars).
  */
 export declare function parseSharedStrings(data: Uint8Array): SharedStrings;
+/**
+ * §18.4.7 `<rPr>` — a run's own font properties (NOT a cellXf index): bold,
+ * italic, underline, strike, colour (rgb), size, vertical alignment and face.
+ * Shared with the comments part, whose `<text>` is the same rich string.
+ *
+ * @param text The run's text.
+ * @param rPr  The parsed `<rPr>` node, if the run has one.
+ */
+export declare function richRun(text: string, rPr: unknown): SheetRichRun;

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

@@ -83,6 +83,14 @@ function extractSi(si) {
 		runs: anyFormatting && runs.length > 0 ? runs : void 0
 	};
 }
+/**
+* §18.4.7 `<rPr>` — a run's own font properties (NOT a cellXf index): bold,
+* italic, underline, strike, colour (rgb), size, vertical alignment and face.
+* Shared with the comments part, whose `<text>` is the same rich string.
+*
+* @param text The run's text.
+* @param rPr  The parsed `<rPr>` node, if the run has one.
+*/
 function richRun(text, rPr) {
 	const p = rPr && typeof rPr === "object" ? rPr : void 0;
 	if (!p) return { text };
@@ -97,6 +105,8 @@ function richRun(text, rPr) {
 	if (sz !== void 0) out.sizePt = sz;
 	const vert = attrStr(p["vertAlign"], "val");
 	if (vert === "superscript" || vert === "subscript") out.vertAlign = vert;
+	const face = attrStr(p["rFont"], "val");
+	if (face) out.fontName = face;
 	return out;
 }
 function has(p, key) {
@@ -132,4 +142,4 @@ function textOf(node) {
 	return "";
 }
 //#endregion
-export { parseSharedStrings };
+export { parseSharedStrings, richRun };

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

@@ -19,6 +19,11 @@ export interface SheetChartRef {
     readonly yPt: number;
     /** Anchor top row (0-based) — used only to order charts on the sheet. */
     readonly anchorRow: number;
+    /**
+     * §20.5.2.3 `<xdr:clientData fPrintsWithSheet="0">` — on the sheet, not on
+     * its paper: the window shows it, a print leaves it out.
+     */
+    readonly screenOnly?: true;
 }
 /**
  * §20.5.2.1 `xdr:pic` — a picture anchored over the grid. The reader reads the
@@ -34,6 +39,11 @@ export interface SheetPicture {
     readonly yPt: number;
     /** Anchor top row (0-based) — used only to order pictures on the sheet. */
     readonly anchorRow: number;
+    /**
+     * §20.5.2.3 `<xdr:clientData fPrintsWithSheet="0">` — on the sheet, not on
+     * its paper: the window shows it, a print leaves it out.
+     */
+    readonly screenOnly?: true;
 }
 /** Both kinds of anchored frame the drawing yields, anchor-ordered. */
 export interface SheetDrawing {
@@ -50,15 +60,41 @@ export interface SheetDrawing {
  * @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.
+ * @param colUnitTwips    The unit its columns are measured in (columnUnitTwips).
+ */
+export declare function parseSheetDrawing(drawingXml: Uint8Array, drawingPartPath: string, pkg: OpcPackage, worksheet: ParsedWorksheet, colUnitTwips?: number): SheetDrawing;
+/**
+ * §20.5.2.3 `<xdr:clientData fPrintsWithSheet>` — whether the drawing prints
+ * with the sheet, which it does unless this says otherwise. A template's tip
+ * for whoever fills it in says otherwise: simple-monthly-budget.xlsx keeps a
+ * "Need to add more entries?" box under its table for the window only, and
+ * printed it ran past the bottom margin of a page LibreOffice prints without.
+ *
+ * @param clientData The anchor's parsed `<xdr:clientData>`, if any.
  */
-export declare function parseSheetDrawing(drawingXml: Uint8Array, drawingPartPath: string, pkg: OpcPackage, worksheet: ParsedWorksheet): SheetDrawing;
+export declare function printsWithSheet(clientData: unknown): boolean;
+/**
+ * Whether a drawing anchored here starts ON the sheet. A cell offset cannot be
+ * negative in anything Excel writes, and a drawing that begins before the
+ * sheet's own corner is one LibreOffice does not import at all (its drawing
+ * fragment keeps only an anchor rectangle at X ≥ 0, Y ≥ 0). tdf66668.xlsx is
+ * LibreOffice's own export of a sheet that reads from the right: each of its
+ * 24 notes left behind a white box the size of the whole sheet at a negative
+ * offset, and drawn they buried every value under them.
+ */
+export declare function onTheSheet(xPt: number, yPt: number): boolean;
 /**
  * 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.
+ *
+ * @param ws        The sheet.
+ * @param unitTwips The unit its columns are measured in — the grid's own
+ *                  (columnUnitTwips), or Excel's 7px digit.
+ * @returns The accessor.
  */
-export declare function makeColWidthPt(ws: ParsedWorksheet): (col: number) => number;
+export declare function makeColWidthPt(ws: ParsedWorksheet, unitTwips?: number): (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.

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

@@ -1,5 +1,5 @@
 import { emuToPt } from "../core/ir/units.js";
-import { columnTwips } from "./print-model.js";
+import { columnTwips, defaultColumnTwips } from "./print-model.js";
 import { XMLParser } from "fast-xml-parser";
 //#region src/excel/sheet-drawing.ts
 var CHART_URI = "http://schemas.openxmlformats.org/drawingml/2006/chart";
@@ -21,15 +21,16 @@ var TWIPS_PER_PT = 20;
 * @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.
+* @param colUnitTwips    The unit its columns are measured in (columnUnitTwips).
 */
-function parseSheetDrawing(drawingXml, drawingPartPath, pkg, worksheet) {
+function parseSheetDrawing(drawingXml, drawingPartPath, pkg, worksheet, colUnitTwips) {
 	const root = parser.parse(new TextDecoder().decode(drawingXml))["wsDr"];
 	if (!root || typeof root !== "object") return {
 		charts: [],
 		pictures: []
 	};
 	const rootObj = root;
-	const colWidthPt = makeColWidthPt(worksheet);
+	const colWidthPt = makeColWidthPt(worksheet, colUnitTwips);
 	const rowHeightPt = makeRowHeightPt(worksheet);
 	const rels = pkg.getPartRelationships(drawingPartPath);
 	const partPathOf = (relId) => {
@@ -70,6 +71,8 @@ function parseSheetDrawing(drawingXml, drawingPartPath, pkg, worksheet) {
 		const posNode = posRaw && typeof posRaw === "object" ? posRaw : void 0;
 		const xPt = posNode ? emuToPt(num(posNode["@_x"]) ?? 0) : from ? spanPt(0, 0, from.col, from.colOffPt, colWidthPt) : 0;
 		const yPt = posNode ? emuToPt(num(posNode["@_y"]) ?? 0) : from ? spanPt(0, 0, from.row, from.rowOffPt, rowHeightPt) : 0;
+		if (!onTheSheet(xPt, yPt)) continue;
+		const screenOnly = !printsWithSheet(a["clientData"]) ? { screenOnly: true } : {};
 		if (chartRelId) {
 			const path = partPathOf(chartRelId);
 			if (path) charts.push({
@@ -78,7 +81,8 @@ function parseSheetDrawing(drawingXml, drawingPartPath, pkg, worksheet) {
 				heightPt,
 				xPt,
 				yPt,
-				anchorRow
+				anchorRow,
+				...screenOnly
 			});
 		} else if (picRelId) {
 			const path = partPathOf(picRelId);
@@ -88,7 +92,8 @@ function parseSheetDrawing(drawingXml, drawingPartPath, pkg, worksheet) {
 				heightPt,
 				xPt,
 				yPt,
-				anchorRow
+				anchorRow,
+				...screenOnly
 			});
 		}
 	}
@@ -99,6 +104,20 @@ function parseSheetDrawing(drawingXml, drawingPartPath, pkg, worksheet) {
 		pictures
 	};
 }
+/**
+* §20.5.2.3 `<xdr:clientData fPrintsWithSheet>` — whether the drawing prints
+* with the sheet, which it does unless this says otherwise. A template's tip
+* for whoever fills it in says otherwise: simple-monthly-budget.xlsx keeps a
+* "Need to add more entries?" box under its table for the window only, and
+* printed it ran past the bottom margin of a page LibreOffice prints without.
+*
+* @param clientData The anchor's parsed `<xdr:clientData>`, if any.
+*/
+function printsWithSheet(clientData) {
+	if (!clientData || typeof clientData !== "object") return true;
+	const flag = clientData["@_fPrintsWithSheet"];
+	return flag !== "0" && flag !== "false";
+}
 function isHiddenDrawing(anchor, kind) {
 	const node = anchor[kind];
 	if (!node || typeof node !== "object") return false;
@@ -152,18 +171,33 @@ function spanPt(from, fromOffPt, to, toOffPt, trackPt) {
 	return span - fromOffPt + toOffPt;
 }
 /**
+* Whether a drawing anchored here starts ON the sheet. A cell offset cannot be
+* negative in anything Excel writes, and a drawing that begins before the
+* sheet's own corner is one LibreOffice does not import at all (its drawing
+* fragment keeps only an anchor rectangle at X ≥ 0, Y ≥ 0). tdf66668.xlsx is
+* LibreOffice's own export of a sheet that reads from the right: each of its
+* 24 notes left behind a white box the size of the whole sheet at a negative
+* offset, and drawn they buried every value under them.
+*/
+function onTheSheet(xPt, yPt) {
+	return xPt >= 0 && yPt >= 0;
+}
+/**
 * 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.
+*
+* @param ws        The sheet.
+* @param unitTwips The unit its columns are measured in — the grid's own
+*                  (columnUnitTwips), or Excel's 7px digit.
+* @returns The accessor.
 */
-function makeColWidthPt(ws) {
-	const widthPt = (chars) => columnTwips(chars, 105) / TWIPS_PER_PT;
+function makeColWidthPt(ws, unitTwips = 105) {
+	const widthPt = (chars) => columnTwips(chars, unitTwips) / TWIPS_PER_PT;
 	return (col) => {
-		for (const c of ws.columns) if (col >= c.min - 1 && col <= c.max - 1) return widthPt(c.widthChars);
-		if (ws.defaultColWidthChars !== void 0) return widthPt(ws.defaultColWidthChars);
-		if (ws.baseColWidthChars !== void 0) return (columnTwips(ws.baseColWidthChars, 105) + 150) / TWIPS_PER_PT;
-		return 960 / TWIPS_PER_PT;
+		for (const c of ws.columns) if (col >= c.min - 1 && col <= c.max - 1) return c.hidden ? 0 : widthPt(c.widthChars);
+		return defaultColumnTwips(ws, unitTwips) / TWIPS_PER_PT;
 	};
 }
 /**
@@ -172,7 +206,7 @@ function makeColWidthPt(ws) {
 */
 function makeRowHeightPt(ws) {
 	return (row) => {
-		for (const r of ws.rowHeights) if (r.row === row) return r.heightPt;
+		for (const r of ws.rowHeights) if (r.row === row) return r.hidden === true ? 0 : r.heightPt;
 		return ws.defaultRowHeightPt ?? 300 / TWIPS_PER_PT;
 	};
 }
@@ -187,4 +221,4 @@ function asArray(v) {
 	return Array.isArray(v) ? v : v !== void 0 ? [v] : [];
 }
 //#endregion
-export { makeColWidthPt, makeRowHeightPt, parseSheetDrawing };
+export { makeColWidthPt, makeRowHeightPt, onTheSheet, parseSheetDrawing, printsWithSheet };

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

@@ -19,8 +19,11 @@ import { PoNode } from '../core/po-helpers.js';
  *                   `<a:fillRef idx>` indexes for a gallery-styled fill.
  * @param themeEffectStyles The theme's `a:effectStyleLst` nodes, which an
  *                   `<a:effectRef idx>` indexes for a gallery-styled shadow.
+ * @param screenOnly Collects the shapes whose anchor does not print with the
+ *                   sheet (§20.5.2.3 `fPrintsWithSheet="0"`).
+ * @param colUnitTwips The unit the sheet's columns are measured in (columnUnitTwips).
  */
-export declare function parseSheetShapes(drawingXml: Uint8Array, worksheet: ParsedWorksheet, colors: ColorResolver, themeLineWidths?: ReadonlyArray<number>, themeFillStyles?: ReadonlyArray<PoNode>, themeEffectStyles?: ReadonlyArray<PoNode>): Array<ShapeBlock>;
+export declare function parseSheetShapes(drawingXml: Uint8Array, worksheet: ParsedWorksheet, colors: ColorResolver, themeLineWidths?: ReadonlyArray<number>, themeFillStyles?: ReadonlyArray<PoNode>, themeEffectStyles?: ReadonlyArray<PoNode>, screenOnly?: Set<ShapeBlock>, colUnitTwips?: number): Array<ShapeBlock>;
 /**
  * The boxes the diagram frames of a drawing occupy, in document order.
  *
@@ -31,9 +34,10 @@ export declare function parseSheetShapes(drawingXml: Uint8Array, worksheet: Pars
  *
  * @param drawingXml The drawing part bytes.
  * @param worksheet  The host worksheet, for the column/row track geometry.
+ * @param colUnitTwips The unit its columns are measured in (columnUnitTwips).
  * @returns One box per diagram frame, in the order the drawing writes them.
  */
-export declare function parseDiagramFrames(drawingXml: Uint8Array, worksheet: ParsedWorksheet): Array<AnchorBox>;
+export declare function parseDiagramFrames(drawingXml: Uint8Array, worksheet: ParsedWorksheet, colUnitTwips?: number): Array<AnchorBox>;
 /**
  * Parse the fallback drawing of a SmartArt diagram (§ MS-ODRAWXML 2.1
  * `dsp:drawing`) into the shapes it lays out.

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

@@ -4,7 +4,7 @@ import { placeholderColors, resolveColorNode } from "../core/drawingml/colors.js
 import { parseFill, parseLine, parseShadow, parseXfrm, shadowFromOuterShdw } from "../word/drawing-parser.js";
 import { parseGeometry, parseTxBody } from "../pptx/slide-parser.js";
 import { parseXml } from "../pptx/pptx-reader.js";
-import { makeColWidthPt, makeRowHeightPt } from "./sheet-drawing.js";
+import { makeColWidthPt, makeRowHeightPt, onTheSheet, printsWithSheet } from "./sheet-drawing.js";
 //#region src/excel/sheet-shape-parser.ts
 var ANCHOR_KINDS = [
 	"xdr:twoCellAnchor",
@@ -87,17 +87,22 @@ function buildShape(sp, box, ns, colors, themeLineWidths, themeFillStyles, theme
 *                   `<a:fillRef idx>` indexes for a gallery-styled fill.
 * @param themeEffectStyles The theme's `a:effectStyleLst` nodes, which an
 *                   `<a:effectRef idx>` indexes for a gallery-styled shadow.
+* @param screenOnly Collects the shapes whose anchor does not print with the
+*                   sheet (§20.5.2.3 `fPrintsWithSheet="0"`).
+* @param colUnitTwips The unit the sheet's columns are measured in (columnUnitTwips).
 */
-function parseSheetShapes(drawingXml, worksheet, colors, themeLineWidths = [], themeFillStyles = [], themeEffectStyles = []) {
+function parseSheetShapes(drawingXml, worksheet, colors, themeLineWidths = [], themeFillStyles = [], themeEffectStyles = [], screenOnly, colUnitTwips) {
 	const wsDr = parseXml(drawingXml).find((n) => poIs(n, "xdr:wsDr"));
 	if (!wsDr) return [];
-	const colWidthPt = makeColWidthPt(worksheet);
+	const colWidthPt = makeColWidthPt(worksheet, colUnitTwips);
 	const rowHeightPt = makeRowHeightPt(worksheet);
 	const shapes = [];
 	for (const anchor of poChildren(wsDr)) {
 		if (!ANCHOR_KINDS.some((k) => poIs(anchor, k))) continue;
 		const anchored = anchorBox(anchor, colWidthPt, rowHeightPt);
 		if (!anchored) continue;
+		const clientData = poChildren(anchor).find((c) => poIs(c, "xdr:clientData"));
+		const printing = printsWithSheet(clientData ? { "@_fPrintsWithSheet": poAttr(clientData, "fPrintsWithSheet") } : void 0);
 		const placed = [];
 		const direct = poChildren(anchor).find((c) => poIs(c, "xdr:sp"));
 		if (direct) placed.push({
@@ -111,11 +116,13 @@ function parseSheetShapes(drawingXml, worksheet, colors, themeLineWidths = [], t
 			if (!shape) continue;
 			shapes.push({
 				shape,
-				anchorRow: box.anchorRow
+				anchorRow: box.anchorRow,
+				screenOnly: !printing
 			});
 		}
 	}
 	shapes.sort((a, b) => a.anchorRow - b.anchorRow);
+	for (const s of shapes) if (s.screenOnly) screenOnly?.add(s.shape);
 	return shapes.map((s) => s.shape);
 }
 /**
@@ -128,12 +135,13 @@ function parseSheetShapes(drawingXml, worksheet, colors, themeLineWidths = [], t
 *
 * @param drawingXml The drawing part bytes.
 * @param worksheet  The host worksheet, for the column/row track geometry.
+* @param colUnitTwips The unit its columns are measured in (columnUnitTwips).
 * @returns One box per diagram frame, in the order the drawing writes them.
 */
-function parseDiagramFrames(drawingXml, worksheet) {
+function parseDiagramFrames(drawingXml, worksheet, colUnitTwips) {
 	const wsDr = parseXml(drawingXml).find((n) => poIs(n, "xdr:wsDr"));
 	if (!wsDr) return [];
-	const colWidthPt = makeColWidthPt(worksheet);
+	const colWidthPt = makeColWidthPt(worksheet, colUnitTwips);
 	const rowHeightPt = makeRowHeightPt(worksheet);
 	const out = [];
 	for (const anchor of poChildren(wsDr)) {
@@ -442,6 +450,10 @@ function withStyleTextColor(text, sp, ns, colors) {
 	};
 }
 function anchorBox(anchor, colWidthPt, rowHeightPt) {
+	const box = anchorBoxAnywhere(anchor, colWidthPt, rowHeightPt);
+	return box && onTheSheet(box.xPt, box.yPt) ? box : void 0;
+}
+function anchorBoxAnywhere(anchor, colWidthPt, rowHeightPt) {
 	const from = marker(poChildren(anchor).find((c) => poIs(c, "xdr:from")));
 	if (poIs(anchor, "xdr:twoCellAnchor")) {
 		const to = marker(poChildren(anchor).find((c) => poIs(c, "xdr:to")));

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

@@ -52,6 +52,23 @@ export interface ProjectSheetOptions {
      * which is which; markdown asks for this, and gets `# Sheet1`.
      */
     readonly sheetHeadings?: boolean;
+    /**
+     * Project for a SCREEN rather than for paper: each sheet as Excel shows it in
+     * its window, not as it prints. One table a sheet with all of its columns —
+     * no column bands, no print scale, no print area or repeated titles, no page
+     * breaks — its drawings where they are anchored, every visible tab including
+     * an empty one, and each sheet a section that names its tab
+     * ({@link Section.sheet}). Headers and footers are print furniture and are
+     * left out. A flowed target that shows the workbook, HTML, asks for this.
+     */
+    readonly screen?: boolean;
+    /**
+     * With {@link screen}: each sheet on a page of its own with room for all of
+     * it — no paper and no margins but a sliver — for a target that draws a
+     * sheet as an image of itself and then cuts the page down to what was drawn
+     * on it (`fitPagesToContent`). The SVG target asks for this.
+     */
+    readonly wholeSheetPages?: boolean;
 }
 /**
  * Project a {@link SheetDoc} into a {@link FlowDoc} (E-SHEET SA2): each grid sheet