reamkit 1.15.1 → 1.15.3

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,53 @@
 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';
+import { Loss } from '../core/ir/loss.js';
+/**
+ * Excel "character width" → twips: the default font's Maximum Digit Width,
+ * ~7 px at 96 DPI ≈ 5.25 pt ≈ 105 twips.
+ */
 export declare const TWIPS_PER_EXCEL_CHAR = 105;
+/**
+ * ECMA-376 §18.3.1.13 — a `<col width>` measures characters of text, and the
+ * rendered column is that many Maximum Digit Widths PLUS a fixed 5-pixel
+ * padding: `px = chars × MDW + 5`. 5 px at 96 DPI = 3.75 pt = 75 twips.
+ *
+ * Omitting it made every column 75 twips narrow, which compounds: on a sheet of
+ * equal 12-character columns the third one landed ~37 pt left of where
+ * LibreOffice puts it. That {@link DEFAULT_COL_TWIPS} below is 960 is the proof
+ * the padding belongs — 8.43 characters only reaches Excel's documented 64 px
+ * default with it (8.43 × 7 + 5 = 64.01 px = 48.01 pt = 960 twips), so the
+ * default was derived from the full formula while the explicit path dropped it.
+ */
+export declare const COL_PADDING_TWIPS = 75;
+/**
+ * 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;
-export declare function sectionFromWorksheet(worksheet: ParsedWorksheet): SectionProperties | undefined;
+/**
+ * Build the page section (paper size + margins) from a worksheet's `<pageSetup>`
+ * / `<pageMargins>`.
+ *
+ * Margins are always set, to Excel's own defaults when the worksheet declares
+ * none (§18.3.1.62) — the renderer's fallback is a word processor's inch, which
+ * is not what a spreadsheet prints. The paper size is left unset when the
+ * worksheet names none, because there the file genuinely holds no answer: Excel
+ * picks by locale and printer, and the renderer's deterministic A4 is as good
+ * as anything we could invent.
+ */
+export declare function sectionFromWorksheet(worksheet: ParsedWorksheet): SectionProperties;
+/**
+ * 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;
@@ -23,8 +65,42 @@ interface PrintModelOptions {
     readonly hyperlinks?: ReadonlyArray<SheetHyperlink>;
     readonly sharedStringRuns?: ReadonlyArray<ReadonlyArray<SheetRichRun> | undefined>;
     readonly now?: Date;
+    readonly losses?: Array<Loss>;
 }
+/**
+ * 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 {};