reamkit 1.31.0 → 1.32.1

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/functions.js

@@ -537,7 +537,7 @@ function parseCriteria(s) {
 	return {
 		kind: "text",
 		negate: op === "<>",
-		re: wildcardToRegExp(text)
+		wildcard: wildcard(text)
 	};
 }
 function matchCriteria(cell, crit) {
@@ -555,22 +555,45 @@ function matchCriteria(cell, crit) {
 	}
 	const text = cell.t === "str" ? cell.v : cell.t === "blank" ? "" : void 0;
 	if (text === void 0) return false;
-	const hit = crit.re.test(text);
+	const hit = crit.wildcard.test(text);
 	return crit.negate ? !hit : hit;
 }
-function wildcardToRegExp(pattern) {
-	let out = "^";
+function wildcard(pattern) {
+	const pieces = [[]];
 	for (let i = 0; i < pattern.length; i++) {
 		const ch = pattern[i];
+		const atoms = pieces[pieces.length - 1];
 		if (ch === "~" && (pattern[i + 1] === "*" || pattern[i + 1] === "?" || pattern[i + 1] === "~")) {
-			out += escapeRe(pattern[i + 1]);
+			atoms.push(escapeRe(pattern[i + 1]));
 			i++;
-		} else if (ch === "*") out += ".*";
-		else if (ch === "?") out += ".";
-		else out += escapeRe(ch);
+		} else if (ch === "*") pieces.push([]);
+		else atoms.push(ch === "?" ? "." : escapeRe(ch));
 	}
-	out += "$";
-	return new RegExp(out, "is");
+	const all = pieces.map((atoms) => ({
+		at: new RegExp(atoms.join(""), "isy"),
+		search: new RegExp(atoms.join(""), "gis"),
+		width: atoms.length
+	}));
+	const fits = (piece, text, at) => {
+		piece.at.lastIndex = at;
+		return piece.at.test(text);
+	};
+	const first = all[0];
+	if (all.length === 1) return { test: (text) => text.length === first.width && fits(first, text, 0) };
+	const last = all[all.length - 1];
+	const between = all.slice(1, -1).filter((piece) => piece.width > 0);
+	return { test(text) {
+		const end = text.length - last.width;
+		if (end < first.width || !fits(first, text, 0) || !fits(last, text, end)) return false;
+		let at = first.width;
+		for (const piece of between) {
+			piece.search.lastIndex = at;
+			const found = piece.search.exec(text);
+			if (found === null || found.index + piece.width > end) return false;
+			at = found.index + piece.width;
+		}
+		return true;
+	} };
 }
 function escapeRe(ch) {
 	return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
@@ -1090,10 +1113,10 @@ function matchFn(args, ev, ctx) {
 	if (len > MAX_SCAN) return err("#N/A");
 	const at = (i) => horizontal ? refGet(range.sheet, ctx, rect.r0, rect.c0 + i) : refGet(range.sheet, ctx, rect.r0 + i, rect.c0);
 	if (type === 0) {
-		const re = target.t === "str" ? wildcardToRegExp(target.v) : void 0;
+		const wild = target.t === "str" ? wildcard(target.v) : void 0;
 		for (let i = 0; i < len; i++) {
 			const cell = at(i);
-			if (re ? cell.t === "str" && re.test(cell.v) : scalarEquals(cell, target)) return num(i + 1);
+			if (wild ? cell.t === "str" && wild.test(cell.v) : scalarEquals(cell, target)) return num(i + 1);
 		}
 		return err("#N/A");
 	}
@@ -1156,10 +1179,10 @@ function lookupFn(args, ev, ctx, vh) {
 	const keyAt = (i) => vertical ? refGet(sh, ctx, rect.r0 + i, rect.c0) : refGet(sh, ctx, rect.r0, rect.c0 + i);
 	const resultAt = (i) => vertical ? refGet(sh, ctx, rect.r0 + i, rect.c0 + line - 1) : refGet(sh, ctx, rect.r0 + line - 1, rect.c0 + i);
 	if (!approx) {
-		const re = target.t === "str" ? wildcardToRegExp(target.v) : void 0;
+		const wild = target.t === "str" ? wildcard(target.v) : void 0;
 		for (let i = 0; i < vecLen; i++) {
 			const k = keyAt(i);
-			if (re ? k.t === "str" && re.test(k.v) : scalarEquals(k, target)) return resultAt(i);
+			if (wild ? k.t === "str" && wild.test(k.v) : scalarEquals(k, target)) return resultAt(i);
 		}
 		return err("#N/A");
 	}

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 };