reamkit 1.15.0 → 1.15.2

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

@@ -1,10 +1,16 @@
 import { CellIcon } from '../core/document-model/index.js';
 import { ConditionalFormat, DefinedName, WorksheetCell, 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
+ * width 0..1 + colour), and/or a leading icon.
+ */
 export interface CfOverride {
     readonly fillHex?: string;
     readonly fontColorHex?: string;
     readonly bold?: boolean;
     readonly italic?: boolean;
+    /** An in-cell data bar: its fraction of the cell width, colour, and optional left offset. */
     readonly dataBar?: {
         readonly fraction: number;
         readonly colorHex: string;
@@ -12,7 +18,39 @@ export interface CfOverride {
     };
     readonly icon?: CellIcon;
 }
+/**
+ * A per-cell lookup returning the {@link CfOverride} for the cell at `(row, col)`,
+ * or undefined when no rule applies. `numericValue` is the cell's comparable number
+ * (undefined for non-numeric cells); `text` is its resolved string — needed by the
+ * text tests and to key duplicate / unique comparisons for non-numeric cells
+ * (empty/undefined for a blank cell).
+ */
 export type CellConditionalFormatter = (row: number, col: number, numericValue: number | undefined, text: string | undefined) => CfOverride | undefined;
+/**
+ * Compile a sheet's `<conditionalFormatting>` rules + the workbook's `<dxfs>` into
+ * a per-cell {@link CellConditionalFormatter}. Returns undefined when the sheet has
+ * no conditional formats (the common case) so callers skip the work entirely and
+ * stay byte-identical.
+ *
+ * @param conditionalFormats The sheet's rules; undefined/empty ⇒ no formatter.
+ * @param styles             The workbook style table (its `dxfs` supply the highlights).
+ * @param cells              The range values the extent rules need
+ *                           (min/max/percentile/mean/frequency); `cellIs` and the
+ *                           text tests ignore it.
+ * @param resolveText        Resolves a cell's string value (shared strings / number
+ *                           format) for the duplicate/unique frequency map — numeric
+ *                           cells key by value without it, so it is only needed for
+ *                           text cells.
+ * @param date1904           The workbook date epoch (feeds the W9 formula engine).
+ * @param now                An injected reference date — never the wall clock —
+ *                           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 ⇒
+ *                           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>;
 }>, currentSheet?: string, definedNames?: ReadonlyArray<DefinedName>): CellConditionalFormatter | undefined;

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

@@ -3,6 +3,31 @@ import { BLANK, bool, err, num, str } 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
+/**
+* Compile a sheet's `<conditionalFormatting>` rules + the workbook's `<dxfs>` into
+* a per-cell {@link CellConditionalFormatter}. Returns undefined when the sheet has
+* no conditional formats (the common case) so callers skip the work entirely and
+* stay byte-identical.
+*
+* @param conditionalFormats The sheet's rules; undefined/empty ⇒ no formatter.
+* @param styles             The workbook style table (its `dxfs` supply the highlights).
+* @param cells              The range values the extent rules need
+*                           (min/max/percentile/mean/frequency); `cellIs` and the
+*                           text tests ignore it.
+* @param resolveText        Resolves a cell's string value (shared strings / number
+*                           format) for the duplicate/unique frequency map — numeric
+*                           cells key by value without it, so it is only needed for
+*                           text cells.
+* @param date1904           The workbook date epoch (feeds the W9 formula engine).
+* @param now                An injected reference date — never the wall clock —
+*                           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 ⇒
+*                           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.
+*/
 function buildConditionalFormatter(conditionalFormats, styles, cells, resolveText, date1904 = false, now, sheetGrids, currentSheet, definedNames) {
 	if (!conditionalFormats || conditionalFormats.length === 0) return void 0;
 	const dxfs = styles.dxfs ?? [];

package/dist/esm/excel/defined-name-ref.d.ts

@@ -1,11 +1,32 @@
+/** A 0-indexed inclusive cell range (the bounding box of a parsed area). */
 export interface CellRange {
     readonly startColumn: number;
     readonly startRow: number;
     readonly endColumn: number;
     readonly endRow: number;
 }
+/**
+ * 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.
+ */
 export declare function parseTitleRowRange(value: string): {
     readonly startRow: number;
     readonly endRow: number;
 } | undefined;
+/**
+ * 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.
+ */
 export declare function parseAreaRef(value: string): CellRange | undefined;

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;