reamkit 1.31.0 → 1.32.0

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;

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

@@ -1,5 +1,5 @@
 import { serialFromDate, timePeriodMatches } from "./formula/dates.js";
-import { BLANK, bool, err, num, str } from "./formula/value.js";
+import { BLANK, bool, err, num, str, toNumber } from "./formula/value.js";
 import { NO_SHIFT, evaluate } from "./formula/eval.js";
 import { compileFormula, evaluateToBool } from "./formula/index.js";
 //#region src/excel/conditional-format.ts
@@ -23,7 +23,8 @@ import { compileFormula, evaluateToBool } from "./formula/index.js";
 *                           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.
@@ -31,21 +32,40 @@ import { compileFormula, evaluateToBool } from "./formula/index.js";
 function buildConditionalFormatter(conditionalFormats, styles, cells, resolveText, date1904 = false, now, sheetGrids, currentSheet, definedNames) {
 	if (!conditionalFormats || conditionalFormats.length === 0) return void 0;
 	const dxfs = styles.dxfs ?? [];
+	const hasExpr = conditionalFormats.some((cf) => cf.rules.some((r) => r.type === "expression"));
+	const formulaStops = conditionalFormats.some((cf) => cf.rules.some((r) => (r.type === "colorScale" || r.type === "dataBar" || r.type === "iconSet") && r.cfvos.some((c) => c.val !== void 0 && !Number.isFinite(Number(c.val)))));
+	const nowSerial = now !== void 0 ? serialFromDate(now, date1904) : void 0;
+	const cross = (hasExpr || formulaStops) && sheetGrids ? {
+		sheets: [...sheetGrids].map(([name, ws]) => ({
+			name,
+			cells: ws.cells,
+			...ws.tables ? { tables: ws.tables } : {}
+		})),
+		...currentSheet !== void 0 ? { currentSheet } : {},
+		definedNames: definedNames ?? []
+	} : void 0;
+	const ctx = hasExpr || formulaStops ? buildEvalContext(cells, resolveText, nowSerial, date1904, cross) : void 0;
+	const stop = ctx ? (formula) => {
+		const compiled = compileFormula(formula.startsWith("=") ? formula.slice(1) : formula);
+		if (!compiled) return void 0;
+		const n = toNumber(evaluate(compiled.ast, ctx, NO_SHIFT), ctx);
+		return typeof n === "number" && Number.isFinite(n) ? n : void 0;
+	} : void 0;
 	const flat = [];
 	for (const cf of conditionalFormats) for (const rule of cf.rules) if (rule.type === "colorScale") flat.push({
 		ranges: cf.ranges,
 		rule,
-		scale: resolveColorScale(rule, cf.ranges, cells)
+		scale: resolveColorScale(rule, cf.ranges, cells, stop)
 	});
 	else if (rule.type === "dataBar") flat.push({
 		ranges: cf.ranges,
 		rule,
-		bar: resolveDataBar(rule, cf.ranges, cells)
+		bar: resolveDataBar(rule, cf.ranges, cells, stop)
 	});
 	else if (rule.type === "iconSet") flat.push({
 		ranges: cf.ranges,
 		rule,
-		iconThresholds: resolveIconThresholds(rule, cf.ranges, cells)
+		iconThresholds: resolveIconThresholds(rule, cf.ranges, cells, stop)
 	});
 	else if (rule.type === "top10") flat.push({
 		ranges: cf.ranges,
@@ -78,17 +98,6 @@ function buildConditionalFormatter(conditionalFormats, styles, cells, resolveTex
 		rule
 	});
 	flat.sort((a, b) => a.rule.priority - b.rule.priority);
-	const hasExpr = flat.some((f) => f.rule.type === "expression");
-	const nowSerial = now !== void 0 ? serialFromDate(now, date1904) : void 0;
-	const cross = hasExpr && sheetGrids ? {
-		sheets: [...sheetGrids].map(([name, ws]) => ({
-			name,
-			cells: ws.cells
-		})),
-		...currentSheet !== void 0 ? { currentSheet } : {},
-		definedNames: definedNames ?? []
-	} : void 0;
-	const ctx = hasExpr ? buildEvalContext(cells, resolveText, nowSerial, date1904, cross) : void 0;
 	return (row, col, value, text, blank) => {
 		if (!hasExpr && value === void 0 && (text === void 0 || text.length === 0)) return;
 		const dupKey = blank === true ? void 0 : dupKeyOf(value, text);
@@ -124,6 +133,7 @@ function buildConditionalFormatter(conditionalFormats, styles, cells, resolveTex
 					if (!icon && value !== void 0 && iconThresholds) {
 						const bucket = iconBucket(iconThresholds, value);
 						icon = iconToCell(rule.iconSet, iconThresholds.length, bucket, rule.reverse ?? false);
+						if (rule.showValue === false) hideValue = true;
 					}
 					break;
 				case "top10":
@@ -206,12 +216,34 @@ function buildEvalContext(cells, resolveText, nowSerial, date1904, cross) {
 		const key = dn.name.toLowerCase();
 		if (dn.localSheetId !== void 0 || !nameMap.has(key)) nameMap.set(key, dn);
 	}
+	const tables = /* @__PURE__ */ new Map();
+	const onThisSheet = [];
+	cross.sheets.forEach((s, i) => {
+		for (const t of s.tables ?? []) {
+			const table = {
+				...i !== currentIdx ? { sheet: i } : {},
+				ref: {
+					r0: t.ref.startRow,
+					c0: t.ref.startColumn,
+					r1: t.ref.endRow,
+					c1: t.ref.endColumn
+				},
+				headerRowCount: t.headerRowCount,
+				totalsRowCount: t.totalsRowCount ?? 0,
+				columns: t.columns ?? []
+			};
+			if (t.name !== void 0) tables.set(t.name.toLowerCase(), table);
+			if (i === currentIdx) onThisSheet.push(table);
+		}
+	});
 	const resolving = /* @__PURE__ */ new Set();
 	const ctx = {
 		...base,
 		sheetIndex: (name) => sheetByName.get(name.toLowerCase()),
 		getCellOn: (sheet, row, col) => sheetData(sheet).byKey.get(row * COLS + col) ?? BLANK,
 		eachCellOn: (sheet, rect, visit) => eachInMap(sheetData(sheet), rect, visit),
+		table: (name) => tables.get(name.toLowerCase()),
+		tableAt: (row, col) => onThisSheet.find((t) => row >= t.ref.r0 && row <= t.ref.r1 && col >= t.ref.c0 && col <= t.ref.c1),
 		resolveName: (rawName) => {
 			const key = rawName.toLowerCase();
 			const dn = nameMap.get(key);
@@ -222,7 +254,6 @@ function buildEvalContext(cells, resolveText, nowSerial, date1904, cross) {
 			if (ast.k === "num") return num(ast.v);
 			if (ast.k === "str") return str(ast.v);
 			if (ast.k === "bool") return bool(ast.v);
-			if (ast.k !== "cell" && ast.k !== "range") return void 0;
 			resolving.add(key);
 			try {
 				return evaluate(ast, ctx, NO_SHIFT);
@@ -358,7 +389,7 @@ function collectRangeValues(cells, ranges) {
 	}
 	return out;
 }
-function resolveColorScale(rule, ranges, cells) {
+function resolveColorScale(rule, ranges, cells, stop) {
 	const vals = collectRangeValues(cells, ranges);
 	if (vals.length === 0) return void 0;
 	const sorted = [...vals].sort((a, b) => a - b);
@@ -366,7 +397,7 @@ function resolveColorScale(rule, ranges, cells) {
 	const vmax = sorted[sorted.length - 1];
 	const thresholds = [];
 	for (const [i, cfvo] of rule.cfvos.entries()) {
-		const t = resolveCfvo(cfvo, vmin, vmax, sorted, i === rule.cfvos.length - 1);
+		const t = resolveCfvo(cfvo, vmin, vmax, sorted, i === rule.cfvos.length - 1, stop);
 		if (t === void 0) return void 0;
 		thresholds.push(t);
 	}
@@ -383,24 +414,26 @@ function resolveColorScale(rule, ranges, cells) {
 		colors
 	};
 }
-function resolveCfvo(cfvo, vmin, vmax, sorted, isLast = false) {
+function resolveCfvo(cfvo, vmin, vmax, sorted, isLast = false, stop) {
+	const given = () => {
+		const n = Number(cfvo.val);
+		if (Number.isFinite(n)) return n;
+		return cfvo.val !== void 0 ? stop?.(cfvo.val) : void 0;
+	};
 	switch (cfvo.type) {
 		case "min":
 		case "autoMin": return vmin;
 		case "max":
 		case "autoMax": return vmax;
-		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 : isLast ? vmax : vmin;
-		}
+		case "num": return given();
+		case "formula": return given() ?? (isLast ? vmax : vmin);
 		case "percent": {
-			const p = Number(cfvo.val);
-			return Number.isFinite(p) ? vmin + (vmax - vmin) * (p / 100) : void 0;
+			const p = given();
+			return p !== void 0 ? vmin + (vmax - vmin) * (p / 100) : void 0;
 		}
 		case "percentile": {
-			const p = Number(cfvo.val);
-			return Number.isFinite(p) ? percentile(sorted, p) : void 0;
+			const p = given();
+			return p !== void 0 ? percentile(sorted, p) : void 0;
 		}
 	}
 }
@@ -445,50 +478,55 @@ function rgbHex([r, g, b]) {
 	const h = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0").toUpperCase();
 	return `${h(r)}${h(g)}${h(b)}`;
 }
-function resolveDataBar(rule, ranges, cells) {
+function resolveDataBar(rule, ranges, cells, stop) {
 	const vals = collectRangeValues(cells, ranges);
 	if (vals.length === 0) return void 0;
 	const sorted = [...vals].sort((a, b) => a - b);
 	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, true);
+	const lower = resolveCfvo(rule.cfvos[0], vmin, vmax, sorted, false, stop);
+	const upper = resolveCfvo(rule.cfvos[1], vmin, vmax, sorted, true, stop);
 	if (lower === void 0 || upper === void 0) return void 0;
 	return {
 		lower,
 		upper,
 		colorHex: rule.colorHex,
 		negativeColorHex: "FF0000",
-		minLen: (rule.minLength ?? 0) / 100,
-		maxLen: (rule.maxLength ?? 100) / 100
+		minLen: (rule.minLength ?? 10) / 100,
+		maxLen: (rule.maxLength ?? 90) / 100,
+		solid: rule.gradient === false
 	};
 }
 function dataBarBar(bar, value) {
+	const solid = bar.solid ? { solid: true } : {};
 	if (bar.lower < 0 && bar.upper > 0) {
 		const axis = -bar.lower / (bar.upper - bar.lower);
 		if (value >= 0) return {
 			fraction: value / bar.upper * (1 - axis),
 			colorHex: bar.colorHex,
-			startFraction: axis
+			startFraction: axis,
+			...solid
 		};
 		const w = Math.abs(value) / Math.abs(bar.lower) * axis;
 		return {
 			fraction: w,
 			colorHex: bar.negativeColorHex,
 			startFraction: axis - w,
-			negative: true
+			negative: true,
+			...solid
 		};
 	}
 	return {
 		fraction: dataBarFraction(bar, value),
-		colorHex: bar.colorHex
+		colorHex: bar.colorHex,
+		...solid
 	};
 }
 function dataBarFraction(bar, value) {
 	const t = bar.upper > bar.lower ? Math.min(1, Math.max(0, (value - bar.lower) / (bar.upper - bar.lower))) : value >= bar.upper ? 1 : 0;
 	return bar.minLen + t * (bar.maxLen - bar.minLen);
 }
-function resolveIconThresholds(rule, ranges, cells) {
+function resolveIconThresholds(rule, ranges, cells, stop) {
 	const vals = collectRangeValues(cells, ranges);
 	if (vals.length === 0) return void 0;
 	const sorted = [...vals].sort((a, b) => a - b);
@@ -496,7 +534,7 @@ function resolveIconThresholds(rule, ranges, cells) {
 	const vmax = sorted[sorted.length - 1];
 	const out = [];
 	for (const cfvo of rule.cfvos) {
-		const t = resolveCfvo(cfvo, vmin, vmax, sorted);
+		const t = resolveCfvo(cfvo, vmin, vmax, sorted, false, stop);
 		if (t === void 0) return void 0;
 		out.push(t);
 	}

package/dist/esm/excel/formula/context.d.ts

@@ -45,4 +45,22 @@ export interface EvalContext {
      * Rect, optionally on another sheet) or a literal scalar; undefined ⇒ `#NAME?`.
      */
     readonly resolveName?: (name: string) => FValue | undefined;
+    /**
+     * §18.5 — a table by its name (case-insensitive), for a structured reference
+     * (`tblIncome[Amount]`); undefined ⇒ `#REF!`.
+     */
+    readonly table?: (name: string) => FormulaTable | undefined;
+    /** The table a cell stands in, for a reference that names none (`[@Amount]`). */
+    readonly tableAt?: (row: number, col: number) => FormulaTable | undefined;
+}
+/** What a structured reference needs of a table (§18.5.1.2). */
+export interface FormulaTable {
+    /** The sheet it is on, when not the formula's own; undefined ⇒ the formula's sheet. */
+    readonly sheet?: number;
+    /** Its whole range — headers, data and totals. */
+    readonly ref: Rect;
+    readonly headerRowCount: number;
+    readonly totalsRowCount: number;
+    /** Its columns' names, left to right. */
+    readonly columns: ReadonlyArray<string>;
 }

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

@@ -56,6 +56,7 @@ function evaluate(ast, ctx, shift) {
 			};
 		}
 		case "name": return ctx.resolveName?.(ast.name) ?? err("#NAME?");
+		case "sref": return structuredRef(ast.ref, ctx, shift);
 		case "array": return {
 			t: "arr",
 			rows: ast.rows.map((row) => row.map((el) => deref(evaluate(el, ctx, shift), ctx)))
@@ -69,6 +70,56 @@ function evaluate(ast, ctx, shift) {
 		case "call": return callFn(ast.name, ast.args, (a) => evaluate(a, ctx, shift), ctx, shift);
 	}
 }
+/**
+* §18.17.6.4 — the cells a structured reference names: the parts of the table
+* it asks for (its data rows when it names none), across the columns it names
+* (all of them when it names none). `#This Row` is the current cell's row.
+*
+* @param ref   The reference.
+* @param ctx   The evaluation context, which knows the tables.
+* @param shift The current cell, for `#This Row` and for a reference naming no table.
+* @returns The range, or `#REF!` for a table, column or part that is not there.
+*/
+function structuredRef(ref, ctx, shift) {
+	const table = ref.table.length > 0 ? ctx.table?.(ref.table) : shift.curRow !== void 0 && shift.curCol !== void 0 ? ctx.tableAt?.(shift.curRow, shift.curCol) : void 0;
+	if (!table) return err("#REF!");
+	const { r0, c0, r1, c1 } = table.ref;
+	const headerEnd = r0 + table.headerRowCount - 1;
+	const totalsStart = r1 - table.totalsRowCount + 1;
+	const rows = (area) => {
+		switch (area) {
+			case "#All": return [r0, r1];
+			case "#Data": return [headerEnd + 1, totalsStart - 1];
+			case "#Headers": return table.headerRowCount > 0 ? [r0, headerEnd] : void 0;
+			case "#Totals": return table.totalsRowCount > 0 ? [totalsStart, r1] : void 0;
+			case "#This Row": return shift.curRow !== void 0 ? [shift.curRow, shift.curRow] : void 0;
+		}
+	};
+	const spans = (ref.areas.length > 0 ? ref.areas : ["#Data"]).map(rows);
+	if (spans.some((s) => s === void 0 || s[1] < s[0])) return err("#REF!");
+	const top = Math.min(...spans.map((s) => s[0]));
+	const bottom = Math.max(...spans.map((s) => s[1]));
+	let left = c0;
+	let right = c1;
+	if (ref.columns) {
+		const at = (name) => table.columns.findIndex((c) => c.toLowerCase() === name.toLowerCase());
+		const a = at(ref.columns[0]);
+		const b = at(ref.columns[1]);
+		if (a < 0 || b < 0) return err("#REF!");
+		left = c0 + Math.min(a, b);
+		right = c0 + Math.max(a, b);
+	}
+	return {
+		t: "ref",
+		rect: {
+			r0: top,
+			c0: left,
+			r1: bottom,
+			c1: right
+		},
+		...table.sheet !== void 0 ? { sheet: table.sheet } : {}
+	};
+}
 function resolveRef(ref, shift) {
 	const row = ref.row.abs ? ref.row.index : ref.row.index + shift.dRow;
 	const col = ref.col.abs ? ref.col.index : ref.col.index + shift.dCol;

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

@@ -1,10 +1,10 @@
 import { Ast } from './parser.js';
 import { EvalContext } from './context.js';
 import { Shift } from './eval.js';
-export type { EvalContext } from './context.js';
+export type { EvalContext, FormulaTable } from './context.js';
 export type { Shift } from './eval.js';
 export type { Scalar, FValue, Rect, FErr } from './value.js';
-export { num, str, bool, err, BLANK } from './value.js';
+export { num, str, bool, err, BLANK, toNumber } from './value.js';
 export { serialFromDate, serialToParts, timePeriodMatches } from './dates.js';
 export { NO_SHIFT, evaluate } from './eval.js';
 /**

package/dist/esm/excel/formula/lexer.d.ts

@@ -1,5 +1,5 @@
 /** The lexical categories the {@link tokenize} pass emits. */
-export type TokenKind = 'num' | 'str' | 'err' | 'word' | 'sheetq' | 'op' | 'eof';
+export type TokenKind = 'num' | 'str' | 'err' | 'word' | 'sheetq' | 'sref' | 'op' | 'eof';
 /** One token: its {@link TokenKind} and the matched source text. */
 export interface Token {
     readonly kind: TokenKind;

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

@@ -21,6 +21,29 @@ function isWordPart(ch) {
 	return isWordStart(ch) || isDigit(ch) || ch === ".";
 }
 /**
+* Where the bracket group that opens at `start` closes: past its matching `]`,
+* nested groups included. A `'` escapes the character after it — a column
+* named `Q[1]` is written `[Q'[1']]`.
+*
+* @param src   The formula source.
+* @param start The index of the opening `[`.
+* @returns The index just past the closing `]`.
+* @throws LexError when the group never closes.
+*/
+function bracketsEnd(src, start) {
+	let depth = 0;
+	for (let j = start; j < src.length; j++) {
+		const c = src[j];
+		if (c === "'") {
+			j++;
+			continue;
+		}
+		if (c === "[") depth++;
+		else if (c === "]" && --depth === 0) return j + 1;
+	}
+	throw new LexError("unclosed [");
+}
+/**
 * Tokenize a formula string into a flat token stream terminated by an `eof`
 * token. Whitespace separates tokens but is otherwise dropped.
 *
@@ -122,6 +145,15 @@ function tokenize(src) {
 		if (isWordStart(ch)) {
 			let j = i + 1;
 			while (j < n && isWordPart(src[j])) j++;
+			if (src[j] === "[") {
+				const end = bracketsEnd(src, j);
+				out.push({
+					kind: "sref",
+					text: src.slice(i, end)
+				});
+				i = end;
+				continue;
+			}
 			out.push({
 				kind: "word",
 				text: src.slice(i, j)
@@ -129,6 +161,15 @@ function tokenize(src) {
 			i = j;
 			continue;
 		}
+		if (ch === "[") {
+			const end = bracketsEnd(src, i);
+			out.push({
+				kind: "sref",
+				text: src.slice(i, end)
+			});
+			i = end;
+			continue;
+		}
 		if (ch === "<" && src[i + 1] === "=") {
 			out.push({
 				kind: "op",

package/dist/esm/excel/formula/parser.d.ts

@@ -15,6 +15,19 @@ export interface CellRef {
     readonly col: Axis;
     readonly row: Axis;
 }
+/** A table's part a structured reference names (§18.17.6.4); none named ⇒ `#Data`. */
+export type TableArea = '#All' | '#Data' | '#Headers' | '#Totals' | '#This Row';
+/**
+ * §18.17.6.4 — a structured reference: the table (empty for the one the cell
+ * is in), the parts of it, and the columns, first to last (all of them when
+ * undefined). `tblIncome[Amount]` is `{ table: 'tblIncome', areas: [],
+ * columns: ['Amount', 'Amount'] }`.
+ */
+export interface StructuredRef {
+    readonly table: string;
+    readonly areas: ReadonlyArray<TableArea>;
+    readonly columns?: readonly [string, string];
+}
 /** The formula syntax tree — a discriminated union over the node kind `k`. */
 export type Ast = {
     readonly k: 'num';
@@ -40,6 +53,9 @@ export type Ast = {
 } | {
     readonly k: 'name';
     readonly name: string;
+} | {
+    readonly k: 'sref';
+    readonly ref: StructuredRef;
 } | {
     readonly k: 'array';
     readonly rows: ReadonlyArray<ReadonlyArray<Ast>>;
@@ -75,3 +91,12 @@ export declare class ParseError extends Error {
  * @throws ParseError on a malformed formula (or {@link LexError} from tokenizing).
  */
 export declare function parse(src: string): Ast;
+/**
+ * §18.17.6.4 — read a structured reference's text: `Table[Col]`, `Table[]`,
+ * `Table[#Totals]`, `Table[[#Headers],[A]:[C]]`, `[@Col]`, `[@[Col 2]]`.
+ *
+ * @param text The token: the table's name, if any, and its brackets.
+ * @returns The reference.
+ * @throws ParseError when the brackets name nothing a table has.
+ */
+export declare function parseStructuredRef(text: string): StructuredRef;