reamkit 1.15.0 → 1.15.2

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;

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

@@ -1,13 +1,17 @@
 //#region src/excel/formula/value.ts
+/** The blank scalar (an empty / absent cell). */
 var BLANK = { t: "blank" };
+/** The logical TRUE scalar. */
 var TRUE = {
 	t: "bool",
 	v: true
 };
+/** The logical FALSE scalar. */
 var FALSE = {
 	t: "bool",
 	v: false
 };
+/** Wrap a number as a scalar; a non-finite result (overflow, 0/0) becomes `#NUM!`. */
 function num(v) {
 	return Number.isFinite(v) ? {
 		t: "num",
@@ -17,24 +21,34 @@ function num(v) {
 		v: "#NUM!"
 	};
 }
+/** Wrap a string as a text scalar. */
 function str(v) {
 	return {
 		t: "str",
 		v
 	};
 }
+/** The {@link TRUE} / {@link FALSE} scalar for a boolean. */
 function bool(v) {
 	return v ? TRUE : FALSE;
 }
+/** Wrap an error code as an error scalar. */
 function err(v) {
 	return {
 		t: "err",
 		v
 	};
 }
+/** Type guard: is the value an error scalar? */
 function isErr(v) {
 	return v.t === "err";
 }
+/**
+* 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.
+*/
 function deref(v, ctx) {
 	if (v.t === "arr") return v.rows[0]?.[0] ?? BLANK;
 	if (v.t !== "ref") return v;
@@ -42,16 +56,27 @@ function deref(v, ctx) {
 	if (r0 === r1 && c0 === c1) return refGet(v.sheet, ctx, r0, c0);
 	return err("#VALUE!");
 }
+/** Visit every scalar element of an array constant, row by row. */
 function arrEach(rows, visit) {
 	for (const row of rows) for (const s of row) visit(s);
 }
+/**
+* Iterate the populated cells of a reference, honouring a cross-sheet qualifier (an
+* absent `eachCellOn` ⇒ no cross-sheet support ⇒ the foreign range is empty).
+*/
 function refEach(v, ctx, visit) {
 	if (v.sheet !== void 0) ctx.eachCellOn?.(v.sheet, v.rect, visit);
 	else ctx.eachCell(v.rect, visit);
 }
+/** Read one absolute cell on a reference's sheet (the current sheet when `sheet` is unset). */
 function refGet(sheet, ctx, row, col) {
 	return sheet !== void 0 ? ctx.getCellOn?.(sheet, row, col) ?? BLANK : ctx.getCell(row, col);
 }
+/**
+* §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.
+*/
 function toNumber(v, ctx) {
 	const s = deref(v, ctx);
 	switch (s.t) {
@@ -67,6 +92,11 @@ function toNumber(v, ctx) {
 		}
 	}
 }
+/**
+* §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}).
+*/
 function toText(v, ctx) {
 	const s = deref(v, ctx);
 	switch (s.t) {

package/dist/esm/excel/header-footer.d.ts

@@ -1,2 +1,11 @@
 import { BodyElement } from '../core/document-model/index.js';
+/**
+ * Expand a print header/footer `&`-code string (E-SHEET W4) into header/footer band
+ * content — one aligned paragraph per non-empty left/centre/right region — or `[]`
+ * when every region is empty. `&P`/`&N` become dynamic PAGE/NUMPAGES field runs the
+ * renderer resolves per page; non-deterministic or unsupported codes are dropped.
+ *
+ * @param formatString The raw `&`-code format string.
+ * @param sheetName    The worksheet tab name, substituted for `&A`.
+ */
 export declare function buildHeaderFooterContent(formatString: string, sheetName: string): Array<BodyElement>;

package/dist/esm/excel/header-footer.js

@@ -1,4 +1,13 @@
 //#region src/excel/header-footer.ts
+/**
+* Expand a print header/footer `&`-code string (E-SHEET W4) into header/footer band
+* content — one aligned paragraph per non-empty left/centre/right region — or `[]`
+* when every region is empty. `&P`/`&N` become dynamic PAGE/NUMPAGES field runs the
+* renderer resolves per page; non-deterministic or unsupported codes are dropped.
+*
+* @param formatString The raw `&`-code format string.
+* @param sheetName    The worksheet tab name, substituted for `&A`.
+*/
 function buildHeaderFooterContent(formatString, sheetName) {
 	const regions = parseHeaderFooterString(formatString, sheetName);
 	const out = [];

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

@@ -1,3 +1,37 @@
+/**
+ * Render a cell's raw stored value through its number format (§18.8.30 built-ins
+ * and §18.8.31 custom codes). Handles `General`, text (`@`), the built-in date /
+ * time formats, custom date codes, and the numeric placeholder grammar (`0` `#`
+ * `,` `.` `%`, scientific notation, quoted literals, `;`-separated sections). An
+ * unknown id, or a value that does not parse as a number, falls back to a plain
+ * render of `rawValue`.
+ *
+ * @param rawValue      The cell's raw stored value (a serial for dates).
+ * @param numFmtId      The number-format id from the cell's `cellXf`.
+ * @param customFormats Custom format codes by id (from `<numFmts>`).
+ * @param date1904      The workbook date epoch (1904 vs the 1900 default).
+ * @returns The formatted display string.
+ */
 export declare function applyNumberFormat(rawValue: string, numFmtId: number, customFormats: ReadonlyMap<number, string>, date1904?: boolean): string;
+/**
+ * Excel serial date → JS `Date`. The default 1900 epoch uses 1899-12-30 as day 0
+ * (so serial 1 is 1900-01-01) and inherits the Lotus 1-2-3 leap-year bug: serial 60
+ * is considered "1900-02-29" which never existed. For serial ≥ 61 the simple
+ * formula is exact; values < 60 are vanishingly rare in business sheets (and our
+ * render is approximate anyway).
+ *
+ * The 1904 epoch (legacy Mac Excel) uses 1904-01-01 as day 0 and has no leap bug.
+ * Files saved with `<workbookPr date1904="1"/>` store dates offset by exactly 1462
+ * days from the 1900-epoch interpretation.
+ */
 export declare function excelSerialToDate(serial: number, date1904: boolean): Date;
+/**
+ * The inverse over a UTC calendar date: `(year, month0, day)` → the integer Excel
+ * serial day, using the same epoch. Round-trips {@link excelSerialToDate} exactly
+ * for an integer serial (the time-of-day is zero), so a serial → parts → serial
+ * loop is stable. Used by the formula engine's date functions and the `timePeriod`
+ * windows (E-SHEET W9) to map an injected reference date into serial space.
+ *
+ * @param month0 The 0-indexed month (0 = January).
+ */
 export declare function excelSerialFromUtcParts(year: number, month0: number, day: number, date1904: boolean): number;

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

@@ -28,6 +28,20 @@ var BUILTIN_DATE_FORMATS = new Map([
 	[46, "[h]:mm:ss"],
 	[47, "mm:ss.0"]
 ]);
+/**
+* Render a cell's raw stored value through its number format (§18.8.30 built-ins
+* and §18.8.31 custom codes). Handles `General`, text (`@`), the built-in date /
+* time formats, custom date codes, and the numeric placeholder grammar (`0` `#`
+* `,` `.` `%`, scientific notation, quoted literals, `;`-separated sections). An
+* unknown id, or a value that does not parse as a number, falls back to a plain
+* render of `rawValue`.
+*
+* @param rawValue      The cell's raw stored value (a serial for dates).
+* @param numFmtId      The number-format id from the cell's `cellXf`.
+* @param customFormats Custom format codes by id (from `<numFmts>`).
+* @param date1904      The workbook date epoch (1904 vs the 1900 default).
+* @returns The formatted display string.
+*/
 function applyNumberFormat(rawValue, numFmtId, customFormats, date1904 = false) {
 	if (rawValue.length === 0) return "";
 	if (numFmtId === 0) return defaultNumberRender(rawValue);
@@ -41,11 +55,31 @@ function applyNumberFormat(rawValue, numFmtId, customFormats, date1904 = false)
 	if (format === "General") return defaultNumberRender(rawValue);
 	return applyFormatString(rawValue, format);
 }
+/**
+* Excel serial date → JS `Date`. The default 1900 epoch uses 1899-12-30 as day 0
+* (so serial 1 is 1900-01-01) and inherits the Lotus 1-2-3 leap-year bug: serial 60
+* is considered "1900-02-29" which never existed. For serial ≥ 61 the simple
+* formula is exact; values < 60 are vanishingly rare in business sheets (and our
+* render is approximate anyway).
+*
+* The 1904 epoch (legacy Mac Excel) uses 1904-01-01 as day 0 and has no leap bug.
+* Files saved with `<workbookPr date1904="1"/>` store dates offset by exactly 1462
+* days from the 1900-epoch interpretation.
+*/
 function excelSerialToDate(serial, date1904) {
 	const ms = serial * 86400 * 1e3;
 	if (date1904) return new Date(Date.UTC(1904, 0, 1) + ms);
 	return new Date(Date.UTC(1899, 11, 30) + ms);
 }
+/**
+* The inverse over a UTC calendar date: `(year, month0, day)` → the integer Excel
+* serial day, using the same epoch. Round-trips {@link excelSerialToDate} exactly
+* for an integer serial (the time-of-day is zero), so a serial → parts → serial
+* loop is stable. Used by the formula engine's date functions and the `timePeriod`
+* windows (E-SHEET W9) to map an injected reference date into serial space.
+*
+* @param month0 The 0-indexed month (0 = January).
+*/
 function excelSerialFromUtcParts(year, month0, day, date1904) {
 	const epoch = date1904 ? Date.UTC(1904, 0, 1) : Date.UTC(1899, 11, 30);
 	return Math.round((Date.UTC(year, month0, day) - epoch) / 864e5);

package/dist/esm/excel/pivot-table-parser.d.ts

@@ -1,2 +1,10 @@
 import { PivotTable } from '../core/spreadsheet-model/index.js';
+/**
+ * Parse `xl/pivotTables/pivotTableN.xml` (§18.10.1.73) into a {@link PivotTable}:
+ * the output `<location>` (range + header/data offsets), the banded-style flags,
+ * and the row/column total markers derived from `<rowItems>`/`<colItems>` (so the
+ * reader can band the region in the pivot palette — E-PIVOT). The output cells are
+ * already cached in the worksheet, so they render as a normal grid. Returns
+ * undefined when the root or its `ref` is missing.
+ */
 export declare function parsePivotTablePart(data: Uint8Array): PivotTable | undefined;

package/dist/esm/excel/pivot-table-parser.js

@@ -9,6 +9,14 @@ var parser = new XMLParser({
 	parseTagValue: false,
 	removeNSPrefix: true
 });
+/**
+* Parse `xl/pivotTables/pivotTableN.xml` (§18.10.1.73) into a {@link PivotTable}:
+* the output `<location>` (range + header/data offsets), the banded-style flags,
+* and the row/column total markers derived from `<rowItems>`/`<colItems>` (so the
+* reader can band the region in the pivot palette — E-PIVOT). The output cells are
+* already cached in the worksheet, so they render as a normal grid. Returns
+* undefined when the root or its `ref` is missing.
+*/
 function parsePivotTablePart(data) {
 	const def = asObj(parser.parse(decoder.decode(data))["pivotTableDefinition"]);
 	if (!def) return void 0;

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

@@ -1,11 +1,34 @@
 import { BodyElement, 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';
+/**
+ * Excel "character width" → twips. Calibri 11pt default Maximum Digit Width is
+ * ~7 px ≈ 5.25 pt ≈ 105 twips. This is a coarse approximation but the auto-fit
+ * pass refines column widths against the actual cell text anyway.
+ */
 export declare const TWIPS_PER_EXCEL_CHAR = 105;
+/**
+ * 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;
+/**
+ * Excel's default row height is ~15pt = 300 twips. Used (for the `fitToHeight`
+ * estimate) for rows without an explicit `<row ht="..">`.
+ */
 export declare const DEFAULT_ROW_TWIPS = 300;
+/**
+ * Build the page section (paper size + margins) from a worksheet's `<pageSetup>`
+ * / `<pageMargins>`. Returns `undefined` when neither is set, so the renderer
+ * applies its A4 default.
+ */
 export declare function sectionFromWorksheet(worksheet: ParsedWorksheet): SectionProperties | undefined;
+/**
+ * ECMA-376 §18.2.5 — resolve the sheet-scoped `_xlnm.Print_Area` defined name
+ * (`localSheetId` = the sheet's 0-based index) into a clipping range.
+ */
 export declare function resolvePrintArea(definedNames: ReadonlyArray<DefinedName>, sheetIdx: number): CellRange | undefined;
+/** ECMA-376 §18.2.5 — `_xlnm.Print_Titles` → the repeated row range (0-indexed). */
 export declare function resolvePrintTitleRows(definedNames: ReadonlyArray<DefinedName>, sheetIdx: number): {
     readonly startRow: number;
     readonly endRow: number;
@@ -24,7 +47,40 @@ interface PrintModelOptions {
     readonly sharedStringRuns?: ReadonlyArray<ReadonlyArray<SheetRichRun> | undefined>;
     readonly now?: Date;
 }
+/**
+ * Project one worksheet's grid into Flow body elements — a single {@link Table}
+ * (or, when the sheet is wider than the page, several column-banded tables). The
+ * full print model lives here: the used-range/print-area window, merge handling,
+ * the style cascade (fonts/fills/borders/alignment), print scaling, conditional
+ * formatting, sparklines, table/pivot banding, overflow and rotation. Memory- and
+ * text-budget-bounded against untrusted input.
+ *
+ * @param worksheet    The parsed grid + per-sheet geometry.
+ * @param sharedStrings The workbook shared-string table (`t="s"` cells index it).
+ * @param styles       The workbook style table (cellXfs + fonts/fills/borders).
+ * @param date1904     The 1904 date system flag (serial-to-date epoch).
+ * @param print        The print-model knobs (print area, gridlines, title rows, …).
+ * @returns The body elements (one table block, or banded tables); empty for a
+ *   blank or empty-print-area sheet.
+ */
 export declare function worksheetToBody(worksheet: ParsedWorksheet, sharedStrings: ReadonlyArray<string>, styles: XlsxStyles, date1904: boolean, print: PrintModelOptions): Array<BodyElement>;
+/**
+ * Resolve a cell's displayed text from its RAW stored value: shared-string and
+ * inline-string lookup, boolean → `TRUE`/`FALSE`, and the number-format pass
+ * (§18.8) for numeric cells. Error/string/date cells pass through verbatim.
+ *
+ * @param cell         The parsed cell.
+ * @param sharedStrings The shared-string table for `t="s"` cells.
+ * @param styles       The style table (for the cell's number format).
+ * @param date1904     The 1904 date system flag.
+ * @returns The resolved display string.
+ */
 export declare function resolveCellText(cell: WorksheetCell, sharedStrings: ReadonlyArray<string>, styles: XlsxStyles, date1904: boolean): string;
+/**
+ * Project a slicer panel (E-SHEET SV2) into a styled mini-{@link Table} emitted
+ * after the grid: a caption header spanning the button columns, then one button
+ * cell per item — the slicer accent fill + white text when selected, a light
+ * band when not; the last row padded so every row keeps the column count.
+ */
 export declare function slicerTable(slicer: SheetSlicer): Table;
 export {};

package/dist/esm/excel/print-model.js

@@ -16,6 +16,11 @@ var PAPER_SIZES_TWIPS = new Map([
 	[70, [5953, 8392]]
 ]);
 var DEFAULT_PAPER_TWIPS = [11906, 16838];
+/**
+* Build the page section (paper size + margins) from a worksheet's `<pageSetup>`
+* / `<pageMargins>`. Returns `undefined` when neither is set, so the renderer
+* applies its A4 default.
+*/
 function sectionFromWorksheet(worksheet) {
 	const pageSize = pageSizeFromSetup(worksheet.pageSetup);
 	const margins = marginsFromXlsx(worksheet.pageMargins);
@@ -52,9 +57,14 @@ function marginsFromXlsx(margins) {
 }
 var PRINT_AREA_NAME = "_xlnm.Print_Area";
 var PRINT_TITLES_NAME = "_xlnm.Print_Titles";
+/**
+* ECMA-376 §18.2.5 — resolve the sheet-scoped `_xlnm.Print_Area` defined name
+* (`localSheetId` = the sheet's 0-based index) into a clipping range.
+*/
 function resolvePrintArea(definedNames, sheetIdx) {
 	for (const dn of definedNames) if (dn.name === PRINT_AREA_NAME && dn.localSheetId === sheetIdx) return parseAreaRef(dn.value);
 }
+/** ECMA-376 §18.2.5 — `_xlnm.Print_Titles` → the repeated row range (0-indexed). */
 function resolvePrintTitleRows(definedNames, sheetIdx) {
 	for (const dn of definedNames) if (dn.name === PRINT_TITLES_NAME && dn.localSheetId === sheetIdx) return parseTitleRowRange(dn.value);
 }
@@ -97,6 +107,22 @@ function scaleRunFont(props, scale) {
 	};
 }
 var MAX_SHEET_TEXT_CHARS = 1e6;
+/**
+* Project one worksheet's grid into Flow body elements — a single {@link Table}
+* (or, when the sheet is wider than the page, several column-banded tables). The
+* full print model lives here: the used-range/print-area window, merge handling,
+* the style cascade (fonts/fills/borders/alignment), print scaling, conditional
+* formatting, sparklines, table/pivot banding, overflow and rotation. Memory- and
+* text-budget-bounded against untrusted input.
+*
+* @param worksheet    The parsed grid + per-sheet geometry.
+* @param sharedStrings The workbook shared-string table (`t="s"` cells index it).
+* @param styles       The workbook style table (cellXfs + fonts/fills/borders).
+* @param date1904     The 1904 date system flag (serial-to-date epoch).
+* @param print        The print-model knobs (print area, gridlines, title rows, …).
+* @returns The body elements (one table block, or banded tables); empty for a
+*   blank or empty-print-area sheet.
+*/
 function worksheetToBody(worksheet, sharedStrings, styles, date1904, print) {
 	if (worksheet.maxRow < 0 || worksheet.maxColumn < 0) return [];
 	let usedRow = -1;
@@ -384,6 +410,17 @@ function makeVerticalContinuation(merge, colWindowEnd, absR, rowWindowEnd) {
 		}]
 	};
 }
+/**
+* Resolve a cell's displayed text from its RAW stored value: shared-string and
+* inline-string lookup, boolean → `TRUE`/`FALSE`, and the number-format pass
+* (§18.8) for numeric cells. Error/string/date cells pass through verbatim.
+*
+* @param cell         The parsed cell.
+* @param sharedStrings The shared-string table for `t="s"` cells.
+* @param styles       The style table (for the cell's number format).
+* @param date1904     The 1904 date system flag.
+* @returns The resolved display string.
+*/
 function resolveCellText(cell, sharedStrings, styles, date1904) {
 	if (cell.type === "inlineStr") return cell.inlineText ?? "";
 	if (cell.type === "s") {
@@ -698,6 +735,12 @@ function cellHasContent(cell) {
 var SLICER_WIDTH_PT = 108;
 var SLICER_ROW_PT = 16;
 var SLICER_UNSELECTED_HEX = "F2F2F2";
+/**
+* Project a slicer panel (E-SHEET SV2) into a styled mini-{@link Table} emitted
+* after the grid: a caption header spanning the button columns, then one button
+* cell per item — the slicer accent fill + white text when selected, a light
+* band when not; the last row padded so every row keeps the column count.
+*/
 function slicerTable(slicer) {
 	const cols = Math.max(1, slicer.columnCount);
 	const colWidthPt = SLICER_WIDTH_PT / cols;

package/dist/esm/excel/shared-strings-parser.d.ts

@@ -1,6 +1,19 @@
 import { SheetRichRun } from '../core/spreadsheet-model/index.js';
+/**
+ * The flattened text of every shared string (a cell with `t="s"` indexes into it),
+ * plus — for the strings that carry per-run formatting — the parsed rich runs
+ * (E-SHEET W6). `runs[i]` is undefined unless si `i` has ≥ 2 runs OR a single run
+ * that actually sets formatting, so the common plain-text case stays cheap.
+ */
 export interface SharedStrings {
+    /** The flattened text of each shared string, parallel to the `<si>` order. */
     readonly texts: ReadonlyArray<string>;
+    /** Per-index rich runs, parallel to {@link SharedStrings.texts}; `undefined` for plain strings. */
     readonly runs: ReadonlyArray<ReadonlyArray<SheetRichRun> | undefined>;
 }
+/**
+ * Parse `xl/sharedStrings.xml` (§18.4.8) into the deduplicated string table plus,
+ * for rich strings, their per-run formatting. Each string is capped to the Excel
+ * cell limit (32 767 chars).
+ */
 export declare function parseSharedStrings(data: Uint8Array): SharedStrings;

package/dist/esm/excel/shared-strings-parser.js

@@ -14,6 +14,11 @@ var MAX_CELL_CHARS = 32767;
 function capLen(s) {
 	return s.length > MAX_CELL_CHARS ? s.slice(0, MAX_CELL_CHARS) : s;
 }
+/**
+* Parse `xl/sharedStrings.xml` (§18.4.8) into the deduplicated string table plus,
+* for rich strings, their per-run formatting. Each string is capped to the Excel
+* cell limit (32 767 chars).
+*/
 function parseSharedStrings(data) {
 	const xml = decoder.decode(data);
 	const sst = parser.parse(xml)["sst"];