reamkit 1.15.1 → 1.15.2

package/dist/esm/excel/defined-name-ref.js

@@ -30,6 +30,16 @@ function parseSingleArea(token) {
 		return;
 	}
 }
+/**
+* Extract the repeated-row range from an `_xlnm.Print_Titles` value, e.g.
+* `"Sheet1!$1:$2"` (rows 1-2) or `"Sheet1!$A:$B,Sheet1!$1:$1"` (cols A-B + row 1).
+* Only the ROW range is recovered — column titles repeat across horizontal page
+* breaks, which the layout does not paginate.
+*
+* @param value The defined-name value.
+* @returns The 0-indexed inclusive row range, or `undefined` when no pure row
+*          range is present.
+*/
 function parseTitleRowRange(value) {
 	if (!value) return void 0;
 	for (const token of value.split(",")) {
@@ -45,6 +55,16 @@ function parseTitleRowRange(value) {
 		};
 	}
 }
+/**
+* Resolve a `<definedName>` area value (§18.2.5 / §18.17) to the bounding box of
+* every parseable area. A value may be a single cell (`"Sheet1!$A$1"`), a range
+* (`"Sheet1!$A$1:$D$20"`), or several comma-separated areas; the sheet qualifier
+* and `$` absolute markers are stripped. Multiple disjoint areas collapse to one
+* enclosing box (a faithful approximation — Excel prints them in sequence).
+*
+* @param value The defined-name value (e.g. a `_xlnm.Print_Area`).
+* @returns The 0-indexed inclusive bounding box, or `undefined` when no area parses.
+*/
 function parseAreaRef(value) {
 	if (!value) return void 0;
 	let box;

package/dist/esm/excel/form-control-parser.d.ts

@@ -1,6 +1,19 @@
+/** A form control's resolved state from its `ctrlProp` part (E-SHEET W8). */
 export interface FormControlProps {
+    /**
+     * §18.18.18-ish `ST_ObjectType` — `CheckBox`, `Radio`, `Spin`, `Scroll`, `Drop`,
+     * `List`, `Buttons`, `Label`, `GBox`, `Dialog`, `EditBox`, `Note` … (the
+     * producer's spelling kept).
+     */
     readonly objectType?: string;
+    /** Checked state for a check/option button. */
     readonly checked?: boolean;
+    /** Current value for a spin / scroll / list control. */
     readonly value?: number;
 }
+/**
+ * Parse a `xl/ctrlProps/ctrlProp#.xml` part (a single `<formControlPr>`) into the
+ * control's {@link FormControlProps} — its `objectType` plus the bit of state the
+ * listing shows (`checked` for check/option buttons, `val` for spin/scroll/list).
+ */
 export declare function parseFormControlProps(data: Uint8Array): FormControlProps;

package/dist/esm/excel/form-control-parser.js

@@ -7,6 +7,11 @@ var parser = new XMLParser({
 	parseAttributeValue: false,
 	removeNSPrefix: true
 });
+/**
+* Parse a `xl/ctrlProps/ctrlProp#.xml` part (a single `<formControlPr>`) into the
+* control's {@link FormControlProps} — its `objectType` plus the bit of state the
+* listing shows (`checked` for check/option buttons, `val` for spin/scroll/list).
+*/
 function parseFormControlProps(data) {
 	const pr = parser.parse(decoder.decode(data))["formControlPr"];
 	const obj = pr && typeof pr === "object" ? pr : void 0;

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

@@ -1,11 +1,48 @@
 import { FValue, Rect, Scalar } from './value.js';
+/**
+ * Everything a formula needs from the world outside its own syntax tree (E-SHEET
+ * W9): the grid's cached cell values, the injected reference date, and the workbook
+ * date epoch — optionally extended with cross-sheet / defined-name resolution. The
+ * context is the seam that keeps the evaluator pure and deterministic: it never
+ * reads the wall clock or recomputes a cell, only looking up values Excel already
+ * cached.
+ */
 export interface EvalContext {
+    /**
+     * The cached value of the cell at `(row, col)` — both absolute, 0-indexed. An
+     * absent or empty cell yields a blank scalar; the evaluator never recurses into a
+     * referenced cell's own formula (there is none stored — we have only the cached
+     * value), which is exactly why no recalculation engine is needed.
+     */
     readonly getCell: (row: number, col: number) => Scalar;
+    /**
+     * Visit every POPULATED cell within a rectangle (blanks are skipped — they
+     * contribute nothing to SUM/COUNT/COUNTIF). Iterating the sparse cell set keeps an
+     * aggregate over a whole-column range O(populated), not O(rows), mirroring the
+     * colorScale extent scan. The order is unspecified.
+     */
     readonly eachCell: (rect: Rect, visit: (row: number, col: number, value: Scalar) => void) => void;
+    /**
+     * The reference "today" as an Excel serial day (`options.now`, converted with the
+     * workbook epoch). `TODAY()`/`NOW()` and the `timePeriod` windows read it.
+     * undefined ⇒ those clock-relative constructs yield `#VALUE!` / no-op, preserving
+     * determinism when the caller supplies no date.
+     */
     readonly nowSerial: number | undefined;
+    /**
+     * false = 1900 epoch (the default), true = 1904 epoch. Date functions
+     * (YEAR/MONTH/DAY/DATE/WEEKDAY/…) convert serials ↔ calendar with it.
+     */
     readonly date1904: boolean;
+    /** A sheet name (case-insensitive) → its 0-based workbook index, or undefined. */
     readonly sheetIndex?: (name: string) => number | undefined;
+    /** {@link EvalContext.getCell}, but on a specific sheet by index (cross-sheet references). */
     readonly getCellOn?: (sheet: number, row: number, col: number) => Scalar;
+    /** {@link EvalContext.eachCell}, but on a specific sheet by index (cross-sheet references). */
     readonly eachCellOn?: (sheet: number, rect: Rect, visit: (row: number, col: number, value: Scalar) => void) => void;
+    /**
+     * Resolve a defined name (case-insensitive) to its target — a reference value (a
+     * Rect, optionally on another sheet) or a literal scalar; undefined ⇒ `#NAME?`.
+     */
     readonly resolveName?: (name: string) => FValue | undefined;
 }

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

@@ -1,11 +1,34 @@
 import { TimePeriodKind } from '../../core/spreadsheet-model/index.js';
+/** The UTC calendar fields an Excel serial decomposes into. */
 export interface DateParts {
     readonly year: number;
+    /** 1-indexed month (January = 1). */
     readonly month: number;
     readonly day: number;
+    /** Day of week, 0 = Sunday … 6 = Saturday (Excel WEEKDAY type 1 minus 1). */
     readonly dow: number;
 }
+/**
+ * Decompose an Excel serial into UTC calendar parts. A fractional serial is
+ * floored to its day first (the calendar date is time-of-day independent).
+ */
 export declare function serialToParts(serial: number, date1904: boolean): DateParts;
+/**
+ * A UTC Date's calendar day → integer Excel serial. Reads the Date's UTC date
+ * parts (not its instant), so a caller passing `new Date('2026-06-17')`
+ * (UTC midnight) maps to that day regardless of the host time zone.
+ */
 export declare function serialFromDate(d: Date, date1904: boolean): number;
+/**
+ * `(year, month1, day)` → integer serial. Excel's `DATE` rolls out-of-range
+ * months and days (`DATE(2024,13,1)` = 2025-01-01); `Date.UTC` already
+ * normalises, so this inherits the same behaviour.
+ */
 export declare function serialFromYmd(year: number, month1: number, day: number, date1904: boolean): number;
+/**
+ * §18.3.1.10 `timePeriod` — does a cell's date fall in the window relative to
+ * `nowSerial` (the injected reference day)? Windows match Excel's built-in
+ * rules: the week runs Sunday..Saturday; "last 7 days" is today and the previous
+ * six. Both serials are floored to whole days before comparison.
+ */
 export declare function timePeriodMatches(period: TimePeriodKind, cellSerial: number, nowSerial: number, date1904: boolean): boolean;

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

@@ -1,5 +1,9 @@
 import { excelSerialFromUtcParts, excelSerialToDate } from "../number-format.js";
 //#region src/excel/formula/dates.ts
+/**
+* Decompose an Excel serial into UTC calendar parts. A fractional serial is
+* floored to its day first (the calendar date is time-of-day independent).
+*/
 function serialToParts(serial, date1904) {
 	const d = excelSerialToDate(Math.floor(serial), date1904);
 	return {
@@ -9,12 +13,28 @@ function serialToParts(serial, date1904) {
 		dow: d.getUTCDay()
 	};
 }
+/**
+* A UTC Date's calendar day → integer Excel serial. Reads the Date's UTC date
+* parts (not its instant), so a caller passing `new Date('2026-06-17')`
+* (UTC midnight) maps to that day regardless of the host time zone.
+*/
 function serialFromDate(d, date1904) {
 	return excelSerialFromUtcParts(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), date1904);
 }
+/**
+* `(year, month1, day)` → integer serial. Excel's `DATE` rolls out-of-range
+* months and days (`DATE(2024,13,1)` = 2025-01-01); `Date.UTC` already
+* normalises, so this inherits the same behaviour.
+*/
 function serialFromYmd(year, month1, day, date1904) {
 	return excelSerialFromUtcParts(year, month1 - 1, day, date1904);
 }
+/**
+* §18.3.1.10 `timePeriod` — does a cell's date fall in the window relative to
+* `nowSerial` (the injected reference day)? Windows match Excel's built-in
+* rules: the week runs Sunday..Saturday; "last 7 days" is today and the previous
+* six. Both serials are floored to whole days before comparison.
+*/
 function timePeriodMatches(period, cellSerial, nowSerial, date1904) {
 	const cell = Math.floor(cellSerial);
 	const today = Math.floor(nowSerial);

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

@@ -1,11 +1,32 @@
 import { Ast } from './parser.js';
 import { EvalContext } from './context.js';
 import { FValue } from './value.js';
+/**
+ * The cell's offset from the rule origin, added to UNANCHORED reference axes.
+ * `curRow`/`curCol` carry the ABSOLUTE current cell (origin + delta) so `ROW()`/
+ * `COLUMN()` with no argument can report it; absent ({@link NO_SHIFT}) ⇒ those
+ * no-arg forms have no cell to name and yield `#VALUE!`.
+ */
 export interface Shift {
+    /** Row delta from the rule origin, added to an unanchored row axis. */
     readonly dRow: number;
+    /** Column delta from the rule origin, added to an unanchored column axis. */
     readonly dCol: number;
+    /** The absolute current row, for no-arg `ROW()`; absent ⇒ `#VALUE!`. */
     readonly curRow?: number;
+    /** The absolute current column, for no-arg `COLUMN()`; absent ⇒ `#VALUE!`. */
     readonly curCol?: number;
 }
+/** The zero shift — no offset and no current cell (no-arg `ROW`/`COLUMN` → `#VALUE!`). */
 export declare const NO_SHIFT: Shift;
+/**
+ * Evaluate an {@link Ast} against an `EvalContext` and a per-cell {@link Shift},
+ * yielding an `FValue` (a scalar, a reference, or an array). Cells/ranges
+ * evaluate to reference values; scalar operators dereference them.
+ *
+ * @param ast   The syntax tree to evaluate.
+ * @param ctx   The evaluation context (grid access, defined names, date system).
+ * @param shift The current cell's offset from the rule origin.
+ * @returns The computed value.
+ */
 export declare function evaluate(ast: Ast, ctx: EvalContext, shift: Shift): FValue;

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

@@ -1,10 +1,21 @@
 import { bool, deref, err, num, str, toNumber, toText } from "./value.js";
 import { callFn } from "./functions.js";
 //#region src/excel/formula/eval.ts
+/** The zero shift — no offset and no current cell (no-arg `ROW`/`COLUMN` → `#VALUE!`). */
 var NO_SHIFT = {
 	dRow: 0,
 	dCol: 0
 };
+/**
+* Evaluate an {@link Ast} against an `EvalContext` and a per-cell {@link Shift},
+* yielding an `FValue` (a scalar, a reference, or an array). Cells/ranges
+* evaluate to reference values; scalar operators dereference them.
+*
+* @param ast   The syntax tree to evaluate.
+* @param ctx   The evaluation context (grid access, defined names, date system).
+* @param shift The current cell's offset from the rule origin.
+* @returns The computed value.
+*/
 function evaluate(ast, ctx, shift) {
 	switch (ast.k) {
 		case "num": return num(ast.v);

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

@@ -3,5 +3,17 @@ import { EvalContext } from './context.js';
 import { Shift } from './eval.js';
 import { FValue } from './value.js';
 type Ev = (a: Ast) => FValue;
+/**
+ * Dispatch a built-in formula function by name, evaluating its arguments through
+ * `ev`. An unknown or misused function returns `#NAME?`/`#VALUE!` so the calling
+ * conditional-format rule simply does not apply — Ream never guesses.
+ *
+ * @param name  The upper-cased function name (e.g. `SUM`, `VLOOKUP`).
+ * @param args  The unevaluated argument expressions.
+ * @param ev    Evaluator for one argument (closes over the context + shift).
+ * @param ctx   The evaluation context (grid access, defined names, date system).
+ * @param shift The per-cell shift (used by no-arg `ROW`/`COLUMN`).
+ * @returns The function's result value.
+ */
 export declare function callFn(name: string, args: ReadonlyArray<Ast>, ev: Ev, ctx: EvalContext, shift: Shift): FValue;
 export {};

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

@@ -1,6 +1,18 @@
 import { serialFromYmd, serialToParts } from "./dates.js";
 import { arrEach, bool, deref, err, isErr, num, refEach, refGet, str, toBool, toNumber, toText } from "./value.js";
 //#region src/excel/formula/functions.ts
+/**
+* Dispatch a built-in formula function by name, evaluating its arguments through
+* `ev`. An unknown or misused function returns `#NAME?`/`#VALUE!` so the calling
+* conditional-format rule simply does not apply — Ream never guesses.
+*
+* @param name  The upper-cased function name (e.g. `SUM`, `VLOOKUP`).
+* @param args  The unevaluated argument expressions.
+* @param ev    Evaluator for one argument (closes over the context + shift).
+* @param ctx   The evaluation context (grid access, defined names, date system).
+* @param shift The per-cell shift (used by no-arg `ROW`/`COLUMN`).
+* @returns The function's result value.
+*/
 function callFn(name, args, ev, ctx, shift) {
 	switch (name) {
 		case "TRUE": return bool(true);

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

@@ -7,8 +7,29 @@ export type { Scalar, FValue, Rect, FErr } from './value.js';
 export { num, str, bool, err, BLANK } from './value.js';
 export { serialFromDate, serialToParts, timePeriodMatches } from './dates.js';
 export { NO_SHIFT, evaluate } from './eval.js';
+/**
+ * A parsed formula, ready to evaluate against many cells (the AST is compiled once
+ * per conditional-format rule, then evaluated per covered cell with a per-cell
+ * shift).
+ */
 export interface CompiledFormula {
     readonly ast: Ast;
 }
+/**
+ * Parse a formula string into a {@link CompiledFormula}. Returns undefined (rather
+ * than throwing) when the formula cannot be parsed — the caller treats that as a
+ * rule that never applies, which is the correct graceful-loss behaviour for an
+ * unsupported construct.
+ */
 export declare function compileFormula(src: string): CompiledFormula | undefined;
+/**
+ * Evaluate a compiled formula in a cell context and reduce it to the rule's truth
+ * test: the conditional format applies iff the result is the logical TRUE or a
+ * non-zero number (Excel §18.3.1.10). Any error / blank / text / zero — and a
+ * multi-cell result — yields false, so the rule simply does not paint.
+ *
+ * @param compiled The compiled formula from {@link compileFormula}.
+ * @param ctx      The evaluation context (cached grid values + reference date).
+ * @param shift    The per-cell relative-reference shift; defaults to {@link NO_SHIFT}.
+ */
 export declare function evaluateToBool(compiled: CompiledFormula, ctx: EvalContext, shift?: Shift): boolean;

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

@@ -3,6 +3,12 @@ import "./dates.js";
 import { toBool } from "./value.js";
 import { NO_SHIFT, evaluate } from "./eval.js";
 //#region src/excel/formula/index.ts
+/**
+* Parse a formula string into a {@link CompiledFormula}. Returns undefined (rather
+* than throwing) when the formula cannot be parsed — the caller treats that as a
+* rule that never applies, which is the correct graceful-loss behaviour for an
+* unsupported construct.
+*/
 function compileFormula(src) {
 	try {
 		return { ast: parse(src) };
@@ -10,6 +16,16 @@ function compileFormula(src) {
 		return;
 	}
 }
+/**
+* Evaluate a compiled formula in a cell context and reduce it to the rule's truth
+* test: the conditional format applies iff the result is the logical TRUE or a
+* non-zero number (Excel §18.3.1.10). Any error / blank / text / zero — and a
+* multi-cell result — yields false, so the rule simply does not paint.
+*
+* @param compiled The compiled formula from {@link compileFormula}.
+* @param ctx      The evaluation context (cached grid values + reference date).
+* @param shift    The per-cell relative-reference shift; defaults to {@link NO_SHIFT}.
+*/
 function evaluateToBool(compiled, ctx, shift = NO_SHIFT) {
 	return toBool(evaluate(compiled.ast, ctx, shift), ctx) === true;
 }

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

@@ -1,8 +1,20 @@
+/** The lexical categories the {@link tokenize} pass emits. */
 export type TokenKind = 'num' | 'str' | 'err' | 'word' | 'sheetq' | 'op' | 'eof';
+/** One token: its {@link TokenKind} and the matched source text. */
 export interface Token {
     readonly kind: TokenKind;
     readonly text: string;
 }
+/** Thrown when the source cannot be tokenized (bad character, over-long input). */
 export declare class LexError extends Error {
 }
+/**
+ * Tokenize a formula string into a flat token stream terminated by an `eof`
+ * token. Whitespace separates tokens but is otherwise dropped.
+ *
+ * @param src The formula source.
+ * @returns The token list, ending with an `eof` token.
+ * @throws LexError when `src` exceeds the source cap or holds an unexpected
+ *   character / bad error literal.
+ */
 export declare function tokenize(src: string): Array<Token>;

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

@@ -9,6 +9,7 @@ var KNOWN_ERRORS = new Set([
 	"#NUM!",
 	"#N/A"
 ]);
+/** Thrown when the source cannot be tokenized (bad character, over-long input). */
 var LexError = class extends Error {};
 function isDigit(ch) {
 	return ch >= "0" && ch <= "9";
@@ -19,6 +20,15 @@ function isWordStart(ch) {
 function isWordPart(ch) {
 	return isWordStart(ch) || isDigit(ch) || ch === ".";
 }
+/**
+* Tokenize a formula string into a flat token stream terminated by an `eof`
+* token. Whitespace separates tokens but is otherwise dropped.
+*
+* @param src The formula source.
+* @returns The token list, ending with an `eof` token.
+* @throws LexError when `src` exceeds the source cap or holds an unexpected
+*   character / bad error literal.
+*/
 function tokenize(src) {
 	if (src.length > MAX_SOURCE) throw new LexError("formula too long");
 	const out = [];

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

@@ -1,12 +1,21 @@
 import { FErr } from './value.js';
+/**
+ * One coordinate of a cell reference. `abs` records whether the axis was `$`
+ * anchored — an unanchored axis shifts by the cell's offset from the rule's
+ * origin when a conditional-format expression is evaluated per cell.
+ */
 export interface Axis {
+    /** 0-indexed row or column. */
     readonly index: number;
+    /** Whether the axis carried a `$` anchor (stays put under the per-cell shift). */
     readonly abs: boolean;
 }
+/** A single-cell reference: its column and row {@link Axis}es. */
 export interface CellRef {
     readonly col: Axis;
     readonly row: Axis;
 }
+/** The formula syntax tree — a discriminated union over the node kind `k`. */
 export type Ast = {
     readonly k: 'num';
     readonly v: number;
@@ -51,7 +60,18 @@ export type Ast = {
     readonly name: string;
     readonly args: ReadonlyArray<Ast>;
 };
+/** The binary operators the parser recognises (see {@link Ast} `bin` nodes). */
 export type BinOp = '+' | '-' | '*' | '/' | '^' | '&' | '=' | '<>' | '<' | '>' | '<=' | '>=';
+/** Thrown when the token stream is not a well-formed formula. */
 export declare class ParseError extends Error {
 }
+/**
+ * Parse a formula string into an {@link Ast}. Callers (the CF compiler) catch
+ * the throw and treat a parse failure as "rule does not apply" — a formula using
+ * a construct we do not model never misrenders, it just no-ops.
+ *
+ * @param src The formula source.
+ * @returns The parsed syntax tree.
+ * @throws ParseError on a malformed formula (or {@link LexError} from tokenizing).
+ */
 export declare function parse(src: string): Ast;

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

@@ -1,5 +1,6 @@
 import { tokenize } from "./lexer.js";
 //#region src/excel/formula/parser.ts
+/** Thrown when the token stream is not a well-formed formula. */
 var ParseError = class extends Error {};
 var PREC = {
 	"=": 1,
@@ -21,27 +22,49 @@ var MAX_ARGS = 255;
 var CELL_RE = /^(\$?)([A-Za-z]{1,3})(\$?)([0-9]{1,7})$/;
 var MAX_COL = 16383;
 var MAX_ROW = 1048575;
+/**
+* Parse a formula string into an {@link Ast}. Callers (the CF compiler) catch
+* the throw and treat a parse failure as "rule does not apply" — a formula using
+* a construct we do not model never misrenders, it just no-ops.
+*
+* @param src The formula source.
+* @returns The parsed syntax tree.
+* @throws ParseError on a malformed formula (or {@link LexError} from tokenizing).
+*/
 function parse(src) {
 	const parser = new Parser(tokenize(src));
 	const ast = parser.parseExpr(0);
 	parser.expectEof();
 	return ast;
 }
+/** A precedence-climbing (Pratt) parser over a {@link tokenize} token stream. */
 var Parser = class {
 	pos = 0;
 	depth = 0;
+	/** @param toks The token stream to parse (must end with an `eof` token). */
 	constructor(toks) {
 		this.toks = toks;
 	}
+	/** The current token without consuming it. */
 	peek() {
 		return this.toks[this.pos];
 	}
+	/** Consume and return the current token. */
 	next() {
 		return this.toks[this.pos++];
 	}
+	/** Assert the stream is fully consumed; throws `ParseError` on trailing tokens. */
 	expectEof() {
 		if (this.peek().kind !== "eof") throw new ParseError(`trailing tokens at ${this.pos}`);
 	}
+	/**
+	* Parse an expression whose operators bind at least as tightly as `minBp`
+	* (the precedence-climbing entry point).
+	*
+	* @param minBp The minimum binding power; operators below it stop the climb.
+	* @returns The parsed sub-tree.
+	* @throws ParseError when the expression nests past the depth cap or is malformed.
+	*/
 	parseExpr(minBp) {
 		if (++this.depth > MAX_DEPTH) throw new ParseError("expression too deep");
 		let left = this.parseUnary();
@@ -63,6 +86,11 @@ var Parser = class {
 		this.depth--;
 		return left;
 	}
+	/**
+	* Parse a (possibly signed) operand. Unary `+`/`-` bind tighter than `^`
+	* (Excel: `-2^2` = 4), so they live above the binary loop; postfix `%` binds
+	* tighter still.
+	*/
 	parseUnary() {
 		const t = this.peek();
 		if (t.kind === "op" && (t.text === "-" || t.text === "+")) {
@@ -75,6 +103,7 @@ var Parser = class {
 		}
 		return this.parsePostfix();
 	}
+	/** Parse a primary then fold any trailing postfix `%` percent operators. */
 	parsePostfix() {
 		let x = this.parsePrimary();
 		while (this.peek().kind === "op" && this.peek().text === "%") {
@@ -86,6 +115,11 @@ var Parser = class {
 		}
 		return x;
 	}
+	/**
+	* Parse a primary expression: a literal, a parenthesised sub-expression, an
+	* inline array constant, or a word (classified by `parseWord` /
+	* sheet-qualifier handling).
+	*/
 	parsePrimary() {
 		const t = this.next();
 		switch (t.kind) {
@@ -125,6 +159,12 @@ var Parser = class {
 			case "eof": throw new ParseError("unexpected end of formula");
 		}
 	}
+	/**
+	* Classify a `word` token: a `(` directly after it makes it a function call,
+	* regardless of shape (so `LOG10( … )` is the function, bare `LOG10` is the
+	* cell reference); else an A1-shaped word is a cell ref (extended to a range on
+	* a trailing `:`), `TRUE`/`FALSE` a logical, anything else a defined name.
+	*/
 	parseWord(word) {
 		if (this.peek().kind === "op" && this.peek().text === "(") {
 			this.next();
@@ -174,6 +214,11 @@ var Parser = class {
 			name: upper
 		};
 	}
+	/**
+	* Parse a sheet-qualified cell or range — the `!` is already consumed; `sheet`
+	* is the (unquoted) sheet name. `Sheet2!A1` or `Sheet2!A1:B3`. The evaluator
+	* resolves the name against the workbook; an unknown sheet becomes `#REF!`.
+	*/
 	parseSheetCell(sheet) {
 		const t = this.next();
 		if (t.kind !== "word") throw new ParseError("expected a cell after !");
@@ -198,6 +243,12 @@ var Parser = class {
 			sheet
 		};
 	}
+	/**
+	* Parse an inline array constant `{1,2,3}` / `{1,2;3,4}`: rows separated by
+	* `;`, elements by `,`. The opening `{` is already consumed. Elements are
+	* parsed as expressions (so a signed literal like `-1` works) and reduced to
+	* scalars at eval; the element count is capped against a crafted huge array.
+	*/
 	parseArray() {
 		const rows = [];
 		let row = [];
@@ -225,6 +276,7 @@ var Parser = class {
 			rows
 		};
 	}
+	/** Parse a comma-separated function argument list (the `(` already consumed). */
 	parseArgs() {
 		const args = [];
 		if (this.peek().kind === "op" && this.peek().text === ")") return args;
@@ -240,6 +292,7 @@ var Parser = class {
 		}
 		return args;
 	}
+	/** Consume the next token, asserting it is the operator `op`. */
 	expect(op) {
 		const t = this.next();
 		if (t.kind !== "op" || t.text !== op) throw new ParseError(`expected ${op}`);

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

@@ -1,11 +1,21 @@
 import { EvalContext } from './context.js';
+/**
+ * §18.17.2 — the seven error values a formula can carry. Stored as their literal
+ * display text so they round-trip and read naturally in diagnostics.
+ */
 export type FErr = '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A';
+/**
+ * A rectangle of cells (absolute, 0-indexed, inclusive) — the value an `A1:B3`
+ * reference evaluates to. A single cell is a 1×1 rect. Aggregate functions iterate
+ * it; scalar contexts dereference it (1×1 → its value, else `#VALUE!`).
+ */
 export interface Rect {
     readonly r0: number;
     readonly c0: number;
     readonly r1: number;
     readonly c1: number;
 }
+/** One of the five scalar value kinds a formula evaluates to. */
 export type Scalar = {
     readonly t: 'num';
     readonly v: number;
@@ -21,6 +31,19 @@ export type Scalar = {
 } | {
     readonly t: 'blank';
 };
+/**
+ * Any value a formula evaluates to: a {@link Scalar}, a `ref` (a {@link Rect},
+ * optionally cross-sheet), or an `arr` (an inline array constant).
+ *
+ * `sheet` (a workbook sheet index) is set only for a cross-sheet qualifier
+ * (`Sheet2!A1`) or a defined name that targets another sheet; when undefined the
+ * reference is on the rule's own sheet (the common case).
+ *
+ * An `arr` value is an inline array constant (`{1,2;3,4}`) — rows of scalars. It
+ * flattens into aggregates, broadcasts element-wise against a scalar in the
+ * operators, and collapses to its top-left element in a scalar context (Excel's
+ * implicit intersection of a constant array).
+ */
 export type FValue = Scalar | {
     readonly t: 'ref';
     readonly rect: Rect;
@@ -29,24 +52,54 @@ export type FValue = Scalar | {
     readonly t: 'arr';
     readonly rows: ReadonlyArray<ReadonlyArray<Scalar>>;
 };
+/** The blank scalar (an empty / absent cell). */
 export declare const BLANK: Scalar;
+/** The logical TRUE scalar. */
 export declare const TRUE: Scalar;
+/** The logical FALSE scalar. */
 export declare const FALSE: Scalar;
+/** Wrap a number as a scalar; a non-finite result (overflow, 0/0) becomes `#NUM!`. */
 export declare function num(v: number): Scalar;
+/** Wrap a string as a text scalar. */
 export declare function str(v: string): Scalar;
+/** The {@link TRUE} / {@link FALSE} scalar for a boolean. */
 export declare function bool(v: boolean): Scalar;
+/** Wrap an error code as an error scalar. */
 export declare function err(v: FErr): Scalar;
+/** Type guard: is the value an error scalar? */
 export declare function isErr(v: FValue): v is {
     t: 'err';
     v: FErr;
 };
+/**
+ * Collapse a reference to a scalar: a 1×1 rect yields the cell's value (a blank cell
+ * → blank); any larger rect in a scalar context is `#VALUE!` (we do not implement
+ * implicit intersection). An array constant collapses to its top-left element;
+ * non-refs pass through unchanged.
+ */
 export declare function deref(v: FValue, ctx: EvalContext): Scalar;
+/** Visit every scalar element of an array constant, row by row. */
 export declare function arrEach(rows: ReadonlyArray<ReadonlyArray<Scalar>>, visit: (value: Scalar) => void): void;
+/**
+ * Iterate the populated cells of a reference, honouring a cross-sheet qualifier (an
+ * absent `eachCellOn` ⇒ no cross-sheet support ⇒ the foreign range is empty).
+ */
 export declare function refEach(v: {
     readonly rect: Rect;
     readonly sheet?: number;
 }, ctx: EvalContext, visit: (row: number, col: number, value: Scalar) => void): void;
+/** Read one absolute cell on a reference's sheet (the current sheet when `sheet` is unset). */
 export declare function refGet(sheet: number | undefined, ctx: EvalContext, row: number, col: number): Scalar;
+/**
+ * §18.17.3 — number coercion. blank → 0, logical → 1/0, a numeric string → its
+ * number (Excel parses `"5"` and `" 5 "` leniently); non-numeric text → `#VALUE!`.
+ * An error propagates (returned as the {@link FErr}); references are dereferenced first.
+ */
 export declare function toNumber(v: FValue, ctx: EvalContext): number | FErr;
+/**
+ * §18.17.3 — text coercion. A number formats with the shortest round-trip
+ * representation, a logical as `TRUE`/`FALSE`, blank as the empty string. Errors
+ * propagate (returned as the {@link FErr}).
+ */
 export declare function toText(v: FValue, ctx: EvalContext): string | FErr;
 export declare function toBool(v: FValue, ctx: EvalContext): boolean | FErr;