reamkit 1.30.0 → 1.32.0

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;

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

@@ -148,6 +148,10 @@ var Parser = class {
 			case "sheetq":
 				this.expect("!");
 				return this.parseSheetCell(t.text);
+			case "sref": return {
+				k: "sref",
+				ref: parseStructuredRef(t.text)
+			};
 			case "op":
 				if (t.text === "(") {
 					const e = this.parseExpr(0);
@@ -323,5 +327,96 @@ function columnToIndex(letters) {
 	for (let i = 0; i < up.length; i++) idx = idx * 26 + (up.charCodeAt(i) - 64);
 	return idx - 1;
 }
+var AREAS = new Map([
+	["#all", "#All"],
+	["#data", "#Data"],
+	["#headers", "#Headers"],
+	["#totals", "#Totals"],
+	["#this row", "#This Row"]
+]);
+/**
+* §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.
+*/
+function parseStructuredRef(text) {
+	const open = text.indexOf("[");
+	const table = text.slice(0, open);
+	let inner = text.slice(open + 1, -1).trim();
+	const areas = [];
+	let columns;
+	if (inner.startsWith("@")) {
+		areas.push("#This Row");
+		inner = inner.slice(1).trim();
+		if (inner.length > 0 && !inner.startsWith("[")) inner = `[${inner}]`;
+	} else if (inner.length > 0 && !inner.startsWith("[")) inner = `[${inner}]`;
+	for (const item of splitTopLevel(inner)) {
+		const range = splitRange(item);
+		if (range) {
+			columns = [unescapeName(range[0]), unescapeName(range[1])];
+			continue;
+		}
+		const body = item.slice(1, -1);
+		const area = AREAS.get(body.trim().toLowerCase());
+		if (area) areas.push(area);
+		else {
+			const name = unescapeName(body);
+			columns = [name, name];
+		}
+	}
+	return {
+		table,
+		areas,
+		...columns ? { columns } : {}
+	};
+}
+/** The bracket groups of a list `[a],[b]:[c]`, each with its `:` partner. */
+function splitTopLevel(inner) {
+	const out = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < inner.length; i++) {
+		const c = inner[i];
+		if (c === "'") {
+			i++;
+			continue;
+		}
+		if (c === "[") depth++;
+		else if (c === "]") depth--;
+		else if (c === "," && depth === 0) {
+			out.push(inner.slice(start, i).trim());
+			start = i + 1;
+		}
+	}
+	const last = inner.slice(start).trim();
+	if (last.length > 0) out.push(last);
+	for (const item of out) if (!item.startsWith("[") || !item.endsWith("]")) throw new ParseError(`bad structured reference part ${item}`);
+	return out;
+}
+/** `[A]:[C]` → the two columns' bracketed bodies, or undefined for one group. */
+function splitRange(item) {
+	let depth = 0;
+	for (let i = 0; i < item.length; i++) {
+		const c = item[i];
+		if (c === "'") {
+			i++;
+			continue;
+		}
+		if (c === "[") depth++;
+		else if (c === "]") depth--;
+		else if (c === ":" && depth === 0) {
+			const a = item.slice(0, i).trim();
+			const b = item.slice(i + 1).trim();
+			return [a.slice(1, -1), b.slice(1, -1)];
+		}
+	}
+}
+/** A column name as written in a reference, its `'` escapes undone. */
+function unescapeName(name) {
+	return name.trim().replace(/'(.)/g, "$1");
+}
 //#endregion
 export { parse };

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

@@ -1,7 +1,8 @@
-import { BodyElement, SectionProperties, Table } from '../core/document-model/index.js';
+import { BodyElement, CellNoteFlag, SectionProperties, Table } from '../core/document-model/index.js';
 import { CellRange, DefinedName, ParsedWorksheet, SheetRichRun, WorksheetCell, XlsxStyles } from './index.js';
 import { SheetHyperlink, SheetSlicer } from '../core/ir/sheet.js';
 import { Loss } from '../core/ir/loss.js';
+import { DrawingBox } from './column-bands.js';
 /**
  * Excel "character width" → twips: the default font's Maximum Digit Width,
  * ~7 px at 96 DPI ≈ 5.25 pt ≈ 105 twips.
@@ -36,11 +37,37 @@ export declare const COL_PADDING_TWIPS = 75;
  * @returns The rendered column width in twips.
  */
 export declare function columnTwips(chars: number, charTwips: number): number;
+/**
+ * §18.3.1.81 — the DEFAULT column, in twips: the sheet's `defaultColWidth`
+ * where it declares one — a stored width, padding included — and otherwise
+ * `baseColWidth` digits and their padding, rounded up to Excel's step of eight
+ * pixels. Padding a `baseColWidth` twice once stood in for that rounding: it
+ * gives 47668.xlsx's 80px as well, and nothing else.
+ *
+ * @param worksheet The sheet.
+ * @param charTwips The Maximum Digit Width, in twips.
+ * @returns The default column width in twips.
+ */
+export declare function defaultColumnTwips(worksheet: ParsedWorksheet, 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;
+/**
+ * §18.3.1.13 — the unit a sheet's columns are measured in: the Maximum Digit
+ * Width of the workbook's Normal font, in twips — the font's own where the
+ * workbook names it, the face we render with where it names none. A drawing's
+ * anchor counts columns in the same unit, or it lands beside the cells it is
+ * anchored to: 45540_form_Footer.xlsx sets its form in 宋体 12, whose digit
+ * is 8px, and anchored at Excel's 7px its check boxes stood a column off
+ * their labels.
+ *
+ * @param styles       The workbook's styles (its first font is the Normal style's).
+ * @param digitWidthPt The render font's digit width, for a workbook that names no font.
+ * @returns The unit, in twips.
+ */
+export declare function columnUnitTwips(styles: XlsxStyles, digitWidthPt?: number): number;
 /**
  * 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
@@ -94,6 +121,8 @@ export declare function printableWidthPt(worksheet: ParsedWorksheet): number;
  */
 export declare function printableHeightPt(worksheet: ParsedWorksheet): number;
 interface PrintModelOptions {
+    readonly screen?: boolean;
+    readonly image?: boolean;
     readonly printArea?: CellRange;
     readonly gridLines: boolean;
     readonly titleRows?: {
@@ -114,10 +143,16 @@ interface PrintModelOptions {
     readonly bandSink?: {
         lefts: Array<number>;
     };
+    readonly headingSink?: {
+        dxPt: number;
+        dyPt: number;
+    };
+    readonly noteFlags?: ReadonlyMap<string, CellNoteFlag>;
     readonly drawingExtentPt?: {
         readonly widthPt: number;
         readonly heightPt: number;
     };
+    readonly drawingBoxesPt?: ReadonlyArray<DrawingBox>;
     readonly losses?: Array<Loss>;
 }
 /**
@@ -149,6 +184,8 @@ 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;
+/** The key {@link PrintModelOptions.noteFlags} is looked up by: absolute row and column. */
+export declare function noteKey(row: number, col: number): string;
 /**
  * Whether an EMPTY cell still draws something of its own — a fill or a border.
  *