reamkit 1.31.0 → 1.32.1

package/dist/esm/core/spreadsheet-model/types.d.ts

@@ -171,6 +171,12 @@ export interface ParsedWorksheet {
     readonly colBreaks?: ReadonlyArray<number>;
     /** §18.3.1.36 `<drawing r:id>` — the sheet's drawing part (charts/shapes). */
     readonly drawingRelId?: string;
+    /**
+     * §18.3.1.99 — the sheet is a `<chartsheet>`: nothing but a chart, which
+     * prints filling the page, and on a landscape one unless the sheet says
+     * otherwise.
+     */
+    readonly chartSheet?: boolean;
     /**
      * §18.3.1.36 `<legacyDrawing r:id>` — the relationship to the sheet's VML
      * drawing part. A form control put on the sheet by Excel's Forms toolbar is
@@ -226,6 +232,22 @@ export interface ParsedWorksheet {
      * (E-SHEET SE2/SE3).
      */
     readonly pane?: SheetPane;
+    /**
+     * ECMA-376 §18.3.1.87 `<sheetView showGridLines>` — whether the sheet's
+     * window draws the cell gridlines. A VIEW setting, like the pane: what
+     * prints is `<printOptions gridLines>`. Carried for a screen projection and
+     * the round trip; absent ⇒ shown, the default.
+     */
+    readonly showGridLines?: boolean;
+    /**
+     * ECMA-376 §18.3.1.87 `<sheetView rightToLeft>` — the sheet reads from the
+     * right: column A stands at the right edge and the columns run leftward,
+     * and each cell's left and right borders cross over with it. What a cell's
+     * text does is unchanged — it keeps the side its alignment names. Unlike
+     * the pane and the gridlines this one prints: Excel puts the sheet on the
+     * paper the way the window shows it. Absent ⇒ left to right.
+     */
+    readonly rightToLeft?: boolean;
 }
 /**
  * A frozen pane: the count of leading rows / columns frozen in the worksheet
@@ -236,6 +258,28 @@ export interface SheetPane {
     readonly frozenRows: number;
     readonly frozenCols: number;
 }
+/**
+ * §18.18.77 ST_TableStyleType — the regions of a table a table style formats,
+ * in the order they apply (§18.8.41): a later region's format wins where both
+ * say something.
+ */
+export type TableStyleElementType = 'wholeTable' | 'firstColumnStripe' | 'secondColumnStripe' | 'firstRowStripe' | 'secondRowStripe' | 'lastColumn' | 'firstColumn' | 'headerRow' | 'totalRow' | 'firstHeaderCell' | 'lastHeaderCell' | 'firstTotalCell' | 'lastTotalCell';
+/** §18.8.40 — one region's format in a table style: its dxf, and a stripe's band size. */
+export interface TableStyleRegion {
+    readonly dxf: Dxf;
+    /** §18.8.41 `size` — rows (or columns) in one band of a stripe; default 1. */
+    readonly size?: number;
+}
+/** §18.8.40 — a table style, region by region, its colours resolved. */
+export type TableStyleFormat = Partial<Record<TableStyleElementType, TableStyleRegion>>;
+/** §18.8.40 `<tableStyle>` — a style a workbook defines itself: each region's dxf. */
+export interface XlsxTableStyle {
+    readonly elements: ReadonlyArray<{
+        readonly type: TableStyleElementType;
+        readonly dxfId: number;
+        readonly size?: number;
+    }>;
+}
 /**
  * ECMA-376 §18.5.1.2 `<table>` — a structured table over a cell range with a
  * banded style. The raw parse carries the range, header rows and style flags;
@@ -247,6 +291,13 @@ export interface ExcelTable {
     readonly name?: string;
     readonly styleName?: string;
     readonly headerRowCount: number;
+    /** §18.5.1.2 `totalsRowCount` — the totals rows at the foot of the table (default 0). */
+    readonly totalsRowCount?: number;
+    /**
+     * §18.5.1.3 `<tableColumn name>` — the columns' names, left to right: what a
+     * structured reference (`tblIncome[Amount]`) names a column by.
+     */
+    readonly columns?: ReadonlyArray<string>;
     readonly showRowStripes: boolean;
     readonly showColumnStripes: boolean;
     readonly showFirstColumn: boolean;
@@ -259,6 +310,12 @@ export interface ExcelTable {
     readonly headerHex?: string;
     readonly bandHex?: string;
     readonly headerTextHex?: string;
+    /**
+     * §18.8.40 — the style the table names, region by region: one Excel builds
+     * in (TableStyleMedium2) or one the workbook defines, its colours resolved
+     * against the workbook's theme.
+     */
+    readonly style?: TableStyleFormat;
 }
 /**
  * ECMA-376 §18.10.1.73 `<pivotTableDefinition>` — a pivot table. Its OUTPUT
@@ -314,6 +371,14 @@ export interface XlsxFont {
     /** §18.8.37 `<strike/>` — the font is struck through. */
     readonly strike?: boolean;
     readonly colorHex?: string;
+    /**
+     * §18.8.3 — how the `<color>` names the colour, not what it comes to:
+     * `theme:1:0`, `rgb:FF000000`, `indexed:8`, `auto`; undefined for a font with
+     * no `<color>`. Excel lets a table style colour a cell's text only where the
+     * cell names its colour as the Normal style does — `theme="1"` black takes
+     * the style's white, `rgb="FF000000"` black keeps its own.
+     */
+    readonly colorRef?: string;
     readonly name?: string;
 }
 /** §18.8.20 `<fill>` — one fill record: pattern type plus foreground/background colours. */
@@ -343,6 +408,13 @@ export interface XlsxBorder {
     readonly diagonal?: XlsxBorderEdge;
     readonly diagonalUp?: boolean;
     readonly diagonalDown?: boolean;
+    /**
+     * §18.8.4 `<vertical>`/`<horizontal>` — the lines BETWEEN the cells of a range
+     * a differential format covers: a table style's rules between its columns
+     * and between its rows. A cell's own border has no use for them.
+     */
+    readonly vertical?: XlsxBorderEdge;
+    readonly horizontal?: XlsxBorderEdge;
 }
 /** §18.18.40 ST_HorizontalAlignment — `<alignment horizontal>`. */
 export type XlsxHorizontalAlign = 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
@@ -362,6 +434,12 @@ export interface XlsxCellAlignment {
     readonly textRotation?: number;
     /** §18.8.1 `shrinkToFit` — scale the text down so it fits the cell on one line (W6). */
     readonly shrinkToFit?: boolean;
+    /**
+     * §18.8.1 `readingOrder` — `1` left to right, `2` right to left. Absent (or
+     * `0`) is "context": the direction of the text's first strong character,
+     * which is also what a General cell aligns its text by.
+     */
+    readonly readingOrder?: 'ltr' | 'rtl';
 }
 /**
  * §18.8.45 `<xf>` — one cell format record: indices into the font/fill/border/
@@ -395,6 +473,11 @@ export interface XlsxStyles {
      * rules (E-SHEET SC1); only the properties a dxf sets override the base.
      */
     readonly dxfs?: ReadonlyArray<Dxf>;
+    /**
+     * §18.8.42 `<tableStyles>` — the table styles the workbook defines itself,
+     * by name; their regions point into {@link XlsxStyles.dxfs}.
+     */
+    readonly tableStyles?: ReadonlyMap<string, XlsxTableStyle>;
 }
 /** §18.8.14 `<dxf>` — a differential (override) format a `cfRule` applies on match. */
 export interface Dxf {
@@ -489,6 +572,11 @@ export interface CfRuleDataBar {
      * figure does not sit on top of its own gauge.
      */
     readonly showValue?: boolean;
+    /**
+     * The 2009 extension's `<x14:dataBar gradient>` — false paints the bar in
+     * one solid colour, where Excel's default fades it from the axis.
+     */
+    readonly gradient?: boolean;
 }
 /**
  * §18.3.1.49 `<cfRule type="iconSet">` — picks one glyph per cell from a named
@@ -501,6 +589,12 @@ export interface CfRuleIconSet {
     readonly iconSet: string;
     readonly cfvos: ReadonlyArray<Cfvo>;
     readonly reverse?: boolean;
+    /**
+     * §18.3.1.49 `showValue` — false means the cell shows its ICON ONLY, as a
+     * status column of ticks and crosses does: the figure is what the icon
+     * already says.
+     */
+    readonly showValue?: boolean;
 }
 /**
  * §18.3.1.10 `<cfRule type="top10">` — the top (or `bottom`) N values of the
@@ -708,6 +802,8 @@ export interface SheetRichRun {
     readonly sizePt?: number;
     /** §18.4.2 `<vertAlign>` — superscript / subscript within the cell text. */
     readonly vertAlign?: 'superscript' | 'subscript';
+    /** §18.4.5 `<rFont>` — the run's typeface, where the producer names one. */
+    readonly fontName?: string;
 }
 /**
  * §18.18.18 ST_DataValidationType — the constraint a `<dataValidation>`

package/dist/esm/core/style-cascade/resolver.js

@@ -262,8 +262,10 @@ function resolveBodyStyles(body, sheet) {
 	};
 	const visit = (el) => {
 		if (el.kind === "paragraph") visitParagraph(el.paragraph);
-		else if (el.kind === "table") for (const row of el.table.rows) for (const cell of row.cells) for (const child of cell.content) visit(child);
-		else if (el.kind === "shape") {
+		else if (el.kind === "table") {
+			for (const row of el.table.rows) for (const cell of row.cells) for (const child of cell.content) visit(child);
+			for (const drawing of el.table.overlay?.drawings ?? []) visit(drawing);
+		} else if (el.kind === "shape") {
 			const shapeText = (sh) => {
 				for (const child of sh.text?.content ?? []) visit(child);
 				for (const member of sh.children ?? []) shapeText(member.shape);

package/dist/esm/excel/column-bands.d.ts

@@ -1,4 +1,21 @@
 import { BodyElement, TableProperties, TableRow } from '../core/document-model/index.js';
+/** §18.3.1.70 — the width of the row-number column, in twips. */
+export declare const HEADING_COL_TWIPS = 460;
+/**
+ * §18.3.1.70 — how the printed headings stand: the sheet's print scale shrinks
+ * them with it, as it shrinks everything else on the page.
+ */
+export interface HeadingBand {
+    /** How tall the letters row stands — exactly, so a drawing anchored to the
+     *  grid can be moved down by just as much. */
+    readonly lettersPt?: number;
+    /** The row-number column's width, in twips; {@link HEADING_COL_TWIPS} unscaled. */
+    readonly colTwips?: number;
+    /** The size the letters and numbers are set in; the sheet's default unscaled. */
+    readonly fontPt?: number;
+    /** The width of the boxes' lines; 0.5pt unscaled. */
+    readonly lineWidthPt?: number;
+}
 /**
  * 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
@@ -7,14 +24,23 @@ import { BodyElement, TableProperties, TableRow } from '../core/document-model/i
  *
  * @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 columns    The absolute index of each of those columns — a hidden
+ *   one between them is skipped, and so is its letter.
  * @param rowNumbers The absolute 1-based row number of each row.
+ * @param band       How the headings stand, at the print scale.
  * @returns The rows and widths with the heading band added.
  */
-export declare function withHeadingBand(rows: ReadonlyArray<TableRow>, widths: ReadonlyArray<number>, colStart: number, rowNumbers: ReadonlyArray<number>): {
+export declare function withHeadingBand(rows: ReadonlyArray<TableRow>, widths: ReadonlyArray<number>, columns: ReadonlyArray<number>, rowNumbers: ReadonlyArray<number>, band?: HeadingBand): {
     rows: Array<TableRow>;
     widths: Array<number>;
 };
+/** Where a drawing lies on its sheet, in points from the sheet's top-left corner. */
+export interface DrawingBox {
+    readonly xPt: number;
+    readonly yPt: number;
+    readonly widthPt: number;
+    readonly heightPt: number;
+}
 /** A contiguous run of columns that prints together as one band (E-SHEET SE1). */
 export interface ColumnBand {
     /** First local column index (inclusive). */
@@ -50,12 +76,19 @@ export declare function computeColumnBands(columnWidths: ReadonlyArray<number>,
  * @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.
+ *   asks for them: the absolute index of each 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.
+ * @param sheet    §20.5 — where the grid's first column stands on the sheet and
+ *   where its printed drawings lie, at the print scale: each band is framed
+ *   for the drawings over it (TableOverlay) and keeps the rows they cover.
  * @returns One table body element per band, in band order.
  */
 export declare function bandedTables(rows: ReadonlyArray<TableRow>, columnWidths: ReadonlyArray<number>, bands: ReadonlyArray<ColumnBand>, properties: TableProperties, titleRowIndex?: number, drawingReachTwips?: number, headings?: {
-    readonly colStart: number;
+    readonly columns: ReadonlyArray<number>;
     readonly rowNumbers: ReadonlyArray<number>;
+    readonly band?: HeadingBand;
+}, sheet?: {
+    readonly sheetLeftPt: number;
+    readonly drawings: ReadonlyArray<DrawingBox>;
 }): Array<BodyElement>;

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

@@ -1,7 +1,4 @@
-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;
+import { pt, twipsToPt } from "../core/ir/units.js";
 /** The A1-style letters of an absolute column index (0 → A, 26 → AA). */
 function columnLetters(index) {
 	let n = index;
@@ -20,14 +17,17 @@ function columnLetters(index) {
 *
 * @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 columns    The absolute index of each of those columns — a hidden
+*   one between them is skipped, and so is its letter.
 * @param rowNumbers The absolute 1-based row number of each row.
+* @param band       How the headings stand, at the print scale.
 * @returns The rows and widths with the heading band added.
 */
-function withHeadingBand(rows, widths, colStart, rowNumbers) {
+function withHeadingBand(rows, widths, columns, rowNumbers, band = {}) {
+	const { lettersPt, colTwips = 460, fontPt, lineWidthPt = .5 } = band;
 	const border = {
 		style: "single",
-		width: .5,
+		width: lineWidthPt,
 		colorHex: "808080"
 	};
 	const borders = {
@@ -47,15 +47,21 @@ function withHeadingBand(rows, widths, colStart, rowNumbers) {
 				properties: { alignment: "center" },
 				runs: [{
 					text,
-					properties: {}
+					properties: fontPt !== void 0 ? { fontSizePt: pt(fontPt) } : {}
 				}]
 			}
 		}]
 	});
 	const letters = [head("")];
-	for (let i = 0; i < widths.length; i++) letters.push(head(columnLetters(colStart + i)));
+	for (let i = 0; i < widths.length; i++) letters.push(head(columnLetters(columns[i] ?? i)));
 	const out = [{
-		properties: { isHeader: true },
+		properties: {
+			isHeader: true,
+			...lettersPt !== void 0 ? {
+				height: pt(lettersPt),
+				heightRule: "exact"
+			} : {}
+		},
 		cells: letters
 	}];
 	rows.forEach((row, i) => {
@@ -66,7 +72,7 @@ function withHeadingBand(rows, widths, colStart, rowNumbers) {
 	});
 	return {
 		rows: out,
-		widths: [HEADING_COL_TWIPS, ...widths]
+		widths: [colTwips, ...widths]
 	};
 }
 /**
@@ -122,16 +128,33 @@ function computeColumnBands(columnWidths, contentWidthTwips, colBreaks) {
 * @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.
+*   asks for them: the absolute index of each 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.
+* @param sheet    §20.5 — where the grid's first column stands on the sheet and
+*   where its printed drawings lie, at the print scale: each band is framed
+*   for the drawings over it (TableOverlay) and keeps the rows they cover.
 * @returns One table body element per band, in band order.
 */
-function bandedTables(rows, columnWidths, bands, properties, titleRowIndex = -1, drawingReachTwips = 0, headings) {
+function bandedTables(rows, columnWidths, bands, properties, titleRowIndex = -1, drawingReachTwips = 0, headings, sheet) {
 	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 sheetLeftPt = sheet ? sheet.sheetLeftPt + twipsToPt(bandLeft) : 0;
+		const sheetRightPt = sheetLeftPt + grid.reduce((sum, w) => sum + w, 0);
+		const overlayAt = (leftPt) => sheet ? { overlay: {
+			sheetLeftPt: pt(sheetLeftPt),
+			widthPt: pt(sheetRightPt - sheetLeftPt),
+			leftPt: pt(leftPt),
+			drawings: []
+		} } : {};
+		const underDrawing = (row) => {
+			const top = row.properties.sheetTopPt;
+			if (top === void 0 || !sheet) return false;
+			const bottom = top + (row.properties.height ?? 0);
+			return sheet.drawings.some((d) => d.xPt < sheetRightPt && d.xPt + d.widthPt > sheetLeftPt && d.yPt < bottom && d.yPt + d.heightPt > top);
+		};
 		const bandRowNumbers = [...headings?.rowNumbers ?? []];
 		const bandRows = rows.map((row, rowIndex) => {
 			const cells = sliceRowCells(row.cells, band);
@@ -144,7 +167,7 @@ function bandedTables(rows, columnWidths, bands, properties, titleRowIndex = -1,
 			};
 		});
 		if (bandIndex > 0 && !(bandLeft < drawingReachTwips) && !bandRows.some(rowDrawsSomething)) return [];
-		while (bandRows.length > 1 && !rowDrawsSomething(bandRows[bandRows.length - 1])) {
+		while (bandRows.length > 1 && !rowDrawsSomething(bandRows[bandRows.length - 1]) && !underDrawing(bandRows[bandRows.length - 1])) {
 			bandRows.pop();
 			bandRowNumbers.pop();
 		}
@@ -158,11 +181,12 @@ function bandedTables(rows, columnWidths, bands, properties, titleRowIndex = -1,
 			rows: bandRows,
 			numbers: bandRowNumbers
 		}]).map((part) => {
-			const headed = headings ? withHeadingBand(part.rows, bandTwips, headings.colStart + band.start, part.numbers) : void 0;
+			const headed = headings ? withHeadingBand(part.rows, bandTwips, headings.columns.slice(band.start, band.end + 1), part.numbers, headings.band) : void 0;
 			return {
 				kind: "table",
 				table: {
 					properties,
+					...overlayAt(headed ? twipsToPt(headings?.band?.colTwips ?? 460) : 0),
 					grid: headed ? headed.widths.map((w) => twipsToPt(w)) : grid,
 					rows: headed ? leadWithBandBreak(headed.rows) : part.rows
 				}

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

@@ -1,4 +1,5 @@
 import { resolveInternalEntities } from "../core/opc/xml-entities.js";
+import { richRun } from "./shared-strings-parser.js";
 import { XMLParser } from "fast-xml-parser";
 //#region src/excel/comments-parser.ts
 var decoder = new TextDecoder("utf-8");
@@ -32,10 +33,12 @@ function parseLegacyComments(data) {
 		const author = Number.isInteger(authorIdx) ? authors[authorIdx] : void 0;
 		const text = stripAuthorPrefix(richText(obj["text"]), author);
 		if (text.length === 0 && !author) continue;
+		const runs = richRuns(obj["text"]);
 		out.push({
 			ref,
 			...author ? { author } : {},
 			text,
+			...runs.length > 0 ? { runs } : {},
 			threaded: false
 		});
 	}
@@ -95,6 +98,22 @@ function richText(node) {
 	if (direct) return direct;
 	return toArray(obj["r"]).map((r) => textOf(asObject(r)?.["t"])).join("");
 }
+function richRuns(node) {
+	const obj = asObject(node);
+	if (!obj) {
+		const plain = textOf(node);
+		return plain ? [{ text: plain }] : [];
+	}
+	const direct = textOf(obj["t"]);
+	if (direct) return [{ text: direct }];
+	const out = [];
+	for (const r of toArray(obj["r"])) {
+		const run = asObject(r);
+		const text = textOf(run?.["t"]);
+		if (text.length > 0) out.push(richRun(text, run?.["rPr"]));
+	}
+	return out;
+}
 function stripAuthorPrefix(text, author) {
 	if (!author) return text;
 	const prefix = `${author}:`;

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

@@ -1,5 +1,5 @@
 import { CellIcon } from '../core/document-model/index.js';
-import { ConditionalFormat, DefinedName, WorksheetCell, XlsxBorder, XlsxStyles } from '../core/spreadsheet-model/index.js';
+import { ConditionalFormat, DefinedName, ExcelTable, 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
@@ -25,12 +25,14 @@ export interface CfOverride {
         readonly colorHex: string;
         readonly startFraction?: number;
         readonly negative?: boolean;
+        readonly solid?: 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.
+     * its own gauge. §18.3.1.49 `<iconSet showValue="0">` is the same for an
+     * icon: "Show Icon Only".
      */
     readonly hideValue?: boolean;
 }
@@ -69,11 +71,13 @@ blank?: boolean) => CfOverride | undefined;
  *                           driving `TODAY()`/`NOW()` and the `timePeriod` windows;
  *                           absent ⇒ those constructs no-op (deterministic output).
  * @param sheetGrids         The whole workbook, for an `expression` rule that reaches
- *                           another sheet (`Sheet2!A1`) or a defined name; absent ⇒
+ *                           another sheet (`Sheet2!A1`), a defined name or a table
+ *                           by its columns (`tblIncome[Amount]`); absent ⇒
  *                           same-sheet references only.
  * @param currentSheet       The rule sheet's name, for resolving sheet-local names.
  * @param definedNames       The workbook defined names visible to `expression` rules.
  */
 export declare function buildConditionalFormatter(conditionalFormats: ReadonlyArray<ConditionalFormat> | undefined, styles: XlsxStyles, cells: ReadonlyArray<WorksheetCell>, resolveText?: (cell: WorksheetCell) => string, date1904?: boolean, now?: Date, sheetGrids?: ReadonlyMap<string, {
     readonly cells: ReadonlyArray<WorksheetCell>;
+    readonly tables?: ReadonlyArray<ExcelTable>;
 }>, currentSheet?: string, definedNames?: ReadonlyArray<DefinedName>): CellConditionalFormatter | undefined;