reamkit 1.15.1 → 1.15.3

package/dist/esm/core/style-cascade/table.d.ts

@@ -1,2 +1,9 @@
 import { BodyElement, StyleSheet } from '../document-model/index.js';
+/**
+ * Apply table styles across a body (ECMA-376 §17.7.6): for each table, fold its
+ * `basedOn` chain and apply the base + `tblLook`-gated conditional region layers
+ * to every cell's chrome (shading, borders, margins) and run/paragraph text, as
+ * a fallback under direct formatting. Recurses into nested tables and shape
+ * text. Mutates the tree IN PLACE and returns it.
+ */
 export declare function resolveTableStyles(body: ReadonlyArray<BodyElement>, sheet: StyleSheet): ReadonlyArray<BodyElement>;

package/dist/esm/core/style-cascade/table.js

@@ -1,4 +1,11 @@
 //#region src/core/style-cascade/table.ts
+/**
+* Apply table styles across a body (ECMA-376 §17.7.6): for each table, fold its
+* `basedOn` chain and apply the base + `tblLook`-gated conditional region layers
+* to every cell's chrome (shading, borders, margins) and run/paragraph text, as
+* a fallback under direct formatting. Recurses into nested tables and shape
+* text. Mutates the tree IN PLACE and returns it.
+*/
 function resolveTableStyles(body, sheet) {
 	const visit = (el) => {
 		if (el.kind === "table") {

package/dist/esm/core/style-cascade/types.d.ts

@@ -1,5 +1,10 @@
 import { Alignment, FontFamilyMap, NumberingReference, UnderlineStyle, VerticalAlign } from '../document-model/index.js';
 import { Pt } from '../ir/index.js';
+/**
+ * A run's fully-resolved properties: every field required because the cascade
+ * has collapsed all inheritance against document defaults and the style chain.
+ * Consumed directly by the renderer.
+ */
 export interface ResolvedRunProperties {
     readonly bold: boolean;
     readonly italic: boolean;
@@ -10,8 +15,16 @@ export interface ResolvedRunProperties {
     readonly fontFamily: FontFamilyMap;
     readonly verticalAlign: VerticalAlign;
     readonly rtl: boolean;
+    /**
+     * Natural language (`w:lang @w:val`). Optional — only set when the source
+     * specifies one; consumed by the tagged-PDF per-element `/Lang`, never layout.
+     */
     readonly lang?: string;
 }
+/**
+ * A paragraph's fully-resolved properties: every field required, the cascade
+ * having collapsed all inheritance. Consumed directly by the renderer.
+ */
 export interface ResolvedParagraphProperties {
     readonly alignment: Alignment;
     readonly spacingBefore: Pt;
@@ -23,9 +36,23 @@ export interface ResolvedParagraphProperties {
     readonly indentFirstLine: Pt;
     readonly pageBreakBefore: boolean;
     readonly bidi: boolean;
+    /**
+     * ECMA-376 §17.3.1.20 — resolved outline level (0–8). Undefined = body text.
+     * Used only by tagged-PDF heading detection.
+     */
     readonly outlineLevel?: number;
+    /**
+     * The paragraph's style id (e.g. `"Heading2"`), carried through for heading
+     * detection when a style lacks an explicit outline level.
+     */
     readonly styleId?: string;
+    /**
+     * §17.9 list reference, carried through for tagged-PDF list structure
+     * (L/LI nesting) — markers themselves are materialized by `applyNumbering`.
+     */
     readonly numbering?: NumberingReference;
 }
+/** Word's empty-document run defaults (used when `docDefaults` is absent). */
 export declare const DEFAULT_RESOLVED_RUN: ResolvedRunProperties;
+/** Word's empty-document paragraph defaults (used when `docDefaults` is absent). */
 export declare const DEFAULT_RESOLVED_PARAGRAPH: ResolvedParagraphProperties;

package/dist/esm/core/style-cascade/types.js

@@ -1,5 +1,6 @@
 import { halfPtToPt, twipsToPt } from "../ir/units.js";
 //#region src/core/style-cascade/types.ts
+/** Word's empty-document run defaults (used when `docDefaults` is absent). */
 var DEFAULT_RESOLVED_RUN = {
 	bold: false,
 	italic: false,
@@ -11,6 +12,7 @@ var DEFAULT_RESOLVED_RUN = {
 	verticalAlign: "baseline",
 	rtl: false
 };
+/** Word's empty-document paragraph defaults (used when `docDefaults` is absent). */
 var DEFAULT_RESOLVED_PARAGRAPH = {
 	alignment: "left",
 	spacingBefore: twipsToPt(0),

package/dist/esm/core/vector.d.ts

@@ -1,3 +1,7 @@
+/**
+ * One drawing operator of a path, in the y-up local frame. The `op` discriminant
+ * mirrors the PDF path operators noted on each arm (`m`/`l`/`c`/`h`).
+ */
 export type PathSegment = {
     readonly op: 'move';
     readonly x: number;
@@ -17,41 +21,104 @@ export type PathSegment = {
 } | {
     readonly op: 'close';
 };
+/** A single subpath: a sequence of {@link PathSegment}s plus an optional fill rule. */
 export interface VectorPath {
     readonly segments: ReadonlyArray<PathSegment>;
+    /**
+     * Winding rule for filling (§8.5.3.3). Defaults to nonzero. `evenodd` selects
+     * the `*` painting variants (`f*`/`B*`).
+     */
     readonly fillRule?: 'nonzero' | 'evenodd';
 }
+/** A stroke description: colour, width, line cap/join and dash pattern. */
 export interface StrokeStyle {
+    /** Stroke colour as 6-hex, no leading `#`. */
     readonly colorHex: string;
     readonly widthPt: number;
     readonly cap?: 'butt' | 'round' | 'square';
     readonly join?: 'miter' | 'round' | 'bevel';
+    /** Dash pattern in points (§8.4.3.6). Empty/omitted = solid line. */
     readonly dash?: ReadonlyArray<number>;
 }
+/**
+ * One stop of a {@link ShapeGradient}: a colour pinned at a fractional `offset`
+ * along the gradient axis.
+ */
 export interface GradientStop {
+    /** Position along the gradient axis, `0..1`. */
     readonly offset: number;
+    /** Stop colour as 6-hex, no leading `#`. */
     readonly colorHex: string;
 }
+/**
+ * A gradient fill — the format-agnostic vocabulary shared by the shape model
+ * (DrawingML `a:gradFill`) and the readers (PDF axial/radial shadings, EP16). A
+ * linear gradient runs along `angle` (degrees clockwise, 0 = left→right); a
+ * radial gradient runs centre→edge. Stops are sorted, offset `0..1`.
+ */
 export interface ShapeGradient {
     readonly kind: 'linear' | 'radial';
+    /** Linear only: gradient direction in degrees clockwise (0 = left→right). */
     readonly angle?: number;
     readonly stops: ReadonlyArray<GradientStop>;
 }
+/**
+ * A drawable shape: one or more {@link VectorPath}s with a fill (solid or
+ * gradient), an optional stroke, and the CTM that maps its local frame onto the
+ * page.
+ */
 export interface VectorShape {
     readonly paths: ReadonlyArray<VectorPath>;
+    /**
+     * Non-stroking fill colour (6-hex). Omitted = no fill. When `fillGradient` is
+     * present this carries its solid approximation (writers without gradient
+     * support, e.g. the plain PDF emitter, paint this instead).
+     */
     readonly fillColorHex?: string;
+    /**
+     * A gradient fill (EP16). Writers that support gradients (SVG) prefer this
+     * over `fillColorHex`.
+     */
     readonly fillGradient?: ShapeGradient;
+    /** Stroke description. Omitted = no stroke. */
     readonly stroke?: StrokeStyle;
+    /**
+     * CTM applied via `cm` (§8.3.4): maps the local frame onto the page. The
+     * 6-tuple is `[a b c d e f]` of the matrix `[[a b 0][c d 0][e f 1]]`.
+     */
     readonly transform: readonly [number, number, number, number, number, number];
 }
+/** Fluent builder so geometry modules read like the shape they describe. */
 export declare class PathBuilder {
     private readonly segments;
+    /** Begin a new subpath at `(x, y)`. */
     moveTo(x: number, y: number): this;
+    /** Add a straight segment to `(x, y)`. */
     lineTo(x: number, y: number): this;
+    /** Add a cubic Bézier to `(x, y)` with control points `(x1, y1)` and `(x2, y2)`. */
     cubicTo(x1: number, y1: number, x2: number, y2: number, x: number, y: number): this;
+    /** Append already-built segments (e.g. an arc decomposed into cubics). */
     append(segments: ReadonlyArray<PathSegment>): this;
+    /** Close the current subpath back to its start. */
     close(): this;
+    /** Snapshot the accumulated segments as a {@link VectorPath}. */
     build(fillRule?: 'nonzero' | 'evenodd'): VectorPath;
 }
+/**
+ * Compose the page flip with a local→page CTM built in the y-up frame, so the
+ * stored transform targets the top-left frame the PageDoc schema froze on.
+ * The flip is an involution: the PDF emitter applies the same operation to
+ * recover the y-up matrix. Negating the linear part only flips sign bits
+ * (exact in IEEE 754); the y-translation is the one component that re-rounds.
+ *
+ * @param m          The local→page CTM 6-tuple `[a b c d e f]`.
+ * @param pageHeight The page height the y-translation flips about.
+ */
 export declare function flipTransform(m: readonly [number, number, number, number, number, number], pageHeight: number): [number, number, number, number, number, number];
+/**
+ * SVG path-data string from `segments`, in raw coordinates (the caller's
+ * transform maps the local frame into the target one).
+ *
+ * @param fmt Number formatter applied to every coordinate.
+ */
 export declare function svgPathData(segments: ReadonlyArray<PathSegment>, fmt: (n: number) => string): string;

package/dist/esm/core/vector.js

@@ -1,6 +1,8 @@
 //#region src/core/vector.ts
+/** Fluent builder so geometry modules read like the shape they describe. */
 var PathBuilder = class {
 	segments = [];
+	/** Begin a new subpath at `(x, y)`. */
 	moveTo(x, y) {
 		this.segments.push({
 			op: "move",
@@ -9,6 +11,7 @@ var PathBuilder = class {
 		});
 		return this;
 	}
+	/** Add a straight segment to `(x, y)`. */
 	lineTo(x, y) {
 		this.segments.push({
 			op: "line",
@@ -17,6 +20,7 @@ var PathBuilder = class {
 		});
 		return this;
 	}
+	/** Add a cubic Bézier to `(x, y)` with control points `(x1, y1)` and `(x2, y2)`. */
 	cubicTo(x1, y1, x2, y2, x, y) {
 		this.segments.push({
 			op: "cubic",
@@ -29,14 +33,17 @@ var PathBuilder = class {
 		});
 		return this;
 	}
+	/** Append already-built segments (e.g. an arc decomposed into cubics). */
 	append(segments) {
 		for (const s of segments) this.segments.push(s);
 		return this;
 	}
+	/** Close the current subpath back to its start. */
 	close() {
 		this.segments.push({ op: "close" });
 		return this;
 	}
+	/** Snapshot the accumulated segments as a {@link VectorPath}. */
 	build(fillRule) {
 		return {
 			segments: this.segments.slice(),
@@ -44,6 +51,16 @@ var PathBuilder = class {
 		};
 	}
 };
+/**
+* Compose the page flip with a local→page CTM built in the y-up frame, so the
+* stored transform targets the top-left frame the PageDoc schema froze on.
+* The flip is an involution: the PDF emitter applies the same operation to
+* recover the y-up matrix. Negating the linear part only flips sign bits
+* (exact in IEEE 754); the y-translation is the one component that re-rounds.
+*
+* @param m          The local→page CTM 6-tuple `[a b c d e f]`.
+* @param pageHeight The page height the y-translation flips about.
+*/
 function flipTransform(m, pageHeight) {
 	return [
 		m[0],
@@ -54,6 +71,12 @@ function flipTransform(m, pageHeight) {
 		pageHeight - m[5]
 	];
 }
+/**
+* SVG path-data string from `segments`, in raw coordinates (the caller's
+* transform maps the local frame into the target one).
+*
+* @param fmt Number formatter applied to every coordinate.
+*/
 function svgPathData(segments, fmt) {
 	const parts = [];
 	for (const s of segments) if (s.op === "move") parts.push(`M ${fmt(s.x)} ${fmt(s.y)}`);

package/dist/esm/excel/activex-parser.d.ts

@@ -1,9 +1,40 @@
+/** An ActiveX control's visible state from its property bag / binary stream (E-SHEET W10). */
 export interface ActiveXProps {
+    /** The control's displayed text (CommandButton/Label/CheckBox/OptionButton). */
     readonly caption?: string;
+    /**
+     * The control's state/value as persisted (`"1"`/`"0"` for a checkbox/option, the
+     * text for a textbox, a number for a spin/scroll).
+     */
     readonly value?: string;
+    /** OptionButton group membership (mutually-exclusive set). */
     readonly groupName?: string;
 }
+/**
+ * Parse a `xl/activeX/activeX#.xml` part (an `<ax:ocx>` whose `<ax:ocxPr name
+ * value>` children persist the visible state) into {@link ActiveXProps}. Reads the
+ * caption / value / group name; returns `{}` for a non-property-bag control.
+ */
 export declare function parseActiveX(data: Uint8Array): ActiveXProps;
+/**
+ * Map an ActiveX `<oleObject progId>` to the affordance key the projection switches
+ * on: `Forms.CheckBox.1 → 'checkbox'`, `Forms.CommandButton.1 → 'button'`, …. An
+ * unknown progId falls back to a generic `'control'`.
+ */
 export declare function activeXType(progId: string | undefined): string;
+/**
+ * The `<ax:ocx r:id>` of a control whose state is persisted to a binary stream
+ * (`persistStreamInit` / `persistStream` / `persistStorage`) rather than to
+ * `<ax:ocxPr>`; the reader resolves it (through the `activeX#.xml` part's own
+ * relationships) to the `activeX#.bin`. Returns undefined for a property-bag
+ * control (the `.bin` is not needed).
+ */
 export declare function activeXBinRelId(xmlData: Uint8Array): string | undefined;
+/**
+ * Parse an `activeX#.bin` (a `persistStreamInit` MorphDataControl) for its caption,
+ * value and group name, per [MS-OFORMS] §2.2.5. Returns `{}` for any non-MorphData
+ * stream (a CFB storage, a CommandButton/Label, a structurally implausible blob) —
+ * a graceful miss, never a wrong caption. Bounds-checked throughout; any overflow
+ * bails to `{}`.
+ */
 export declare function parseActiveXBin(data: Uint8Array): ActiveXProps;

package/dist/esm/excel/activex-parser.js

@@ -7,6 +7,11 @@ var parser = new XMLParser({
 	parseAttributeValue: false,
 	removeNSPrefix: true
 });
+/**
+* Parse a `xl/activeX/activeX#.xml` part (an `<ax:ocx>` whose `<ax:ocxPr name
+* value>` children persist the visible state) into {@link ActiveXProps}. Reads the
+* caption / value / group name; returns `{}` for a non-property-bag control.
+*/
 function parseActiveX(data) {
 	const ocx = asObject(parser.parse(decoder.decode(data))["ocx"]);
 	if (!ocx) return {};
@@ -26,6 +31,11 @@ function parseActiveX(data) {
 		...groupName !== void 0 ? { groupName } : {}
 	};
 }
+/**
+* Map an ActiveX `<oleObject progId>` to the affordance key the projection switches
+* on: `Forms.CheckBox.1 → 'checkbox'`, `Forms.CommandButton.1 → 'button'`, …. An
+* unknown progId falls back to a generic `'control'`.
+*/
 function activeXType(progId) {
 	switch ((/Forms\.(\w+)\.\d+/i.exec(progId ?? "")?.[1] ?? "").toLowerCase()) {
 		case "checkbox": return "checkbox";
@@ -52,6 +62,13 @@ function strAttr(obj, key) {
 	const v = obj[`@_${key}`];
 	return typeof v === "string" ? v : void 0;
 }
+/**
+* The `<ax:ocx r:id>` of a control whose state is persisted to a binary stream
+* (`persistStreamInit` / `persistStream` / `persistStorage`) rather than to
+* `<ax:ocxPr>`; the reader resolves it (through the `activeX#.xml` part's own
+* relationships) to the `activeX#.bin`. Returns undefined for a property-bag
+* control (the `.bin` is not needed).
+*/
 function activeXBinRelId(xmlData) {
 	const ocx = asObject(parser.parse(decoder.decode(xmlData))["ocx"]);
 	if (!ocx) return void 0;
@@ -112,6 +129,13 @@ function u16le(d, i) {
 function u32le(d, i) {
 	return (d[i] | d[i + 1] << 8 | d[i + 2] << 16 | d[i + 3] << 24) >>> 0;
 }
+/**
+* Parse an `activeX#.bin` (a `persistStreamInit` MorphDataControl) for its caption,
+* value and group name, per [MS-OFORMS] §2.2.5. Returns `{}` for any non-MorphData
+* stream (a CFB storage, a CommandButton/Label, a structurally implausible blob) —
+* a graceful miss, never a wrong caption. Bounds-checked throughout; any overflow
+* bails to `{}`.
+*/
 function parseActiveXBin(data) {
 	if (data.length >= 8 && CFB_MAGIC.every((b, i) => data[i] === b)) return {};
 	let off;

package/dist/esm/excel/cell-reference.d.ts

@@ -1,6 +1,20 @@
+/** A 0-indexed cell address (`A1` → `{ column: 0, row: 0 }`). */
 export interface CellAddress {
     readonly column: number;
     readonly row: number;
 }
+/**
+ * Parse an A1-style cell reference (§18.18.62) into a 0-indexed {@link CellAddress}.
+ * The column letters are base-26 (`A`=1 … `Z`=26, `AA`=27, …); the row is a plain
+ * 1-indexed integer. Both are decremented to 0-indexed on the way out.
+ *
+ * @param ref The reference, e.g. `"AB12"` (case-insensitive column letters).
+ * @returns The 0-indexed column/row.
+ * @throws Error when `ref` has no column letters or a non-positive-integer row.
+ */
 export declare function parseCellRef(ref: string): CellAddress;
+/**
+ * Format a 0-indexed {@link CellAddress} back to an A1-style reference — the
+ * inverse of {@link parseCellRef} (`{ column: 0, row: 0 }` → `"A1"`).
+ */
 export declare function formatCellRef(address: CellAddress): string;

package/dist/esm/excel/cell-reference.js

@@ -3,6 +3,15 @@ var A = 65;
 var Z = 90;
 var a = 97;
 var z = 122;
+/**
+* Parse an A1-style cell reference (§18.18.62) into a 0-indexed {@link CellAddress}.
+* The column letters are base-26 (`A`=1 … `Z`=26, `AA`=27, …); the row is a plain
+* 1-indexed integer. Both are decremented to 0-indexed on the way out.
+*
+* @param ref The reference, e.g. `"AB12"` (case-insensitive column letters).
+* @returns The 0-indexed column/row.
+* @throws Error when `ref` has no column letters or a non-positive-integer row.
+*/
 function parseCellRef(ref) {
 	let i = 0;
 	let column = 0;

package/dist/esm/excel/column-bands.d.ts

@@ -1,7 +1,36 @@
 import { BodyElement, TableProperties, TableRow } from '../core/document-model/index.js';
+/** A contiguous run of columns that prints together as one band (E-SHEET SE1). */
 export interface ColumnBand {
+    /** First local column index (inclusive). */
     readonly start: number;
+    /** Last local column index (inclusive). */
     readonly end: number;
 }
+/**
+ * Greedy fill: accumulate column widths until the next column would overflow the
+ * content width, then start a new band. A manual column break (`colBreaks` holds
+ * local indices that begin a new page) always starts a new band. Every band keeps
+ * at least one column — a single column wider than the page stands alone (the
+ * layout shrinks it, the one case where fitting is unavoidable).
+ *
+ * @param columnWidths     Per-column widths in twips, by local index.
+ * @param contentWidthTwips The printable content width one band must fit within.
+ * @param colBreaks        Local column indices that force a new band.
+ * @returns The bands in left-to-right order.
+ */
 export declare function computeColumnBands(columnWidths: ReadonlyArray<number>, contentWidthTwips: number, colBreaks: ReadonlySet<number>): Array<ColumnBand>;
+/**
+ * Build one table {@link BodyElement} per band from the fully materialised rows +
+ * column widths (twips, local index). Bands after the first force a page break
+ * before their first row, so each band starts on a fresh page. A horizontal span
+ * that crosses a band boundary is clipped to the band it starts in; later bands
+ * render the overlapped columns blank, matching Excel's split-at-the-break
+ * behaviour.
+ *
+ * @param rows         The full sheet rows (every band slices the same rows).
+ * @param columnWidths Per-column widths in twips, by local index.
+ * @param bands        The bands from {@link computeColumnBands}.
+ * @param properties   The shared table properties applied to every band.
+ * @returns One table body element per band, in band order.
+ */
 export declare function bandedTables(rows: ReadonlyArray<TableRow>, columnWidths: ReadonlyArray<number>, bands: ReadonlyArray<ColumnBand>, properties: TableProperties): Array<BodyElement>;

package/dist/esm/excel/column-bands.js

@@ -1,5 +1,17 @@
 import { twipsToPt } from "../core/ir/units.js";
 //#region src/excel/column-bands.ts
+/**
+* Greedy fill: accumulate column widths until the next column would overflow the
+* content width, then start a new band. A manual column break (`colBreaks` holds
+* local indices that begin a new page) always starts a new band. Every band keeps
+* at least one column — a single column wider than the page stands alone (the
+* layout shrinks it, the one case where fitting is unavoidable).
+*
+* @param columnWidths     Per-column widths in twips, by local index.
+* @param contentWidthTwips The printable content width one band must fit within.
+* @param colBreaks        Local column indices that force a new band.
+* @returns The bands in left-to-right order.
+*/
 function computeColumnBands(columnWidths, contentWidthTwips, colBreaks) {
 	const n = columnWidths.length;
 	if (n === 0) return [];
@@ -26,6 +38,20 @@ function computeColumnBands(columnWidths, contentWidthTwips, colBreaks) {
 	});
 	return bands;
 }
+/**
+* Build one table {@link BodyElement} per band from the fully materialised rows +
+* column widths (twips, local index). Bands after the first force a page break
+* before their first row, so each band starts on a fresh page. A horizontal span
+* that crosses a band boundary is clipped to the band it starts in; later bands
+* render the overlapped columns blank, matching Excel's split-at-the-break
+* behaviour.
+*
+* @param rows         The full sheet rows (every band slices the same rows).
+* @param columnWidths Per-column widths in twips, by local index.
+* @param bands        The bands from {@link computeColumnBands}.
+* @param properties   The shared table properties applied to every band.
+* @returns One table body element per band, in band order.
+*/
 function bandedTables(rows, columnWidths, bands, properties) {
 	return bands.map((band, bandIndex) => {
 		return {
@@ -74,13 +100,7 @@ function withColSpan(cell, span) {
 function blankCell(span) {
 	return {
 		properties: span > 1 ? { colSpan: span } : {},
-		content: [{
-			kind: "paragraph",
-			paragraph: {
-				properties: {},
-				runs: []
-			}
-		}]
+		content: []
 	};
 }
 //#endregion

package/dist/esm/excel/comments-parser.d.ts

@@ -1,4 +1,23 @@
 import { SheetComment } from '../core/ir/sheet.js';
+/**
+ * Parse a legacy `xl/comments#.xml` part (§18.7.3/§18.7.6) into {@link SheetComment}s.
+ * `authorId` indexes the `<authors>` list; the text is rich (`<r><t>`) so it
+ * flattens like a shared string. Excel stores a bold "Author:\n" run at the head
+ * of the text — stripped here so the resolved author is not shown twice.
+ */
 export declare function parseLegacyComments(data: Uint8Array): Array<SheetComment>;
+/**
+ * Parse `xl/persons/person.xml` into an `id → displayName` map, used to resolve
+ * the authors of threaded comments.
+ */
 export declare function parsePersons(data: Uint8Array): Map<string, string>;
+/**
+ * Parse a modern `xl/threadedComments/threadedComment#.xml` part (a conversation)
+ * into {@link SheetComment}s. Each entry is one message (replies share the `ref`);
+ * `personId` resolves through `persons`. Entries are returned in document order so
+ * a thread reads top to bottom.
+ *
+ * @param data    The threaded-comments part bytes.
+ * @param persons The `id → displayName` map from {@link parsePersons}.
+ */
 export declare function parseThreadedComments(data: Uint8Array, persons: ReadonlyMap<string, string>): Array<SheetComment>;

package/dist/esm/excel/comments-parser.js

@@ -10,6 +10,12 @@ var parser = new XMLParser({
 	trimValues: false,
 	removeNSPrefix: true
 });
+/**
+* Parse a legacy `xl/comments#.xml` part (§18.7.3/§18.7.6) into {@link SheetComment}s.
+* `authorId` indexes the `<authors>` list; the text is rich (`<r><t>`) so it
+* flattens like a shared string. Excel stores a bold "Author:\n" run at the head
+* of the text — stripped here so the resolved author is not shown twice.
+*/
 function parseLegacyComments(data) {
 	const root = asObject(parser.parse(decoder.decode(data))["comments"]);
 	if (!root) return [];
@@ -33,6 +39,10 @@ function parseLegacyComments(data) {
 	}
 	return out;
 }
+/**
+* Parse `xl/persons/person.xml` into an `id → displayName` map, used to resolve
+* the authors of threaded comments.
+*/
 function parsePersons(data) {
 	const root = asObject(parser.parse(decoder.decode(data))["personList"]);
 	const map = /* @__PURE__ */ new Map();
@@ -45,6 +55,15 @@ function parsePersons(data) {
 	}
 	return map;
 }
+/**
+* Parse a modern `xl/threadedComments/threadedComment#.xml` part (a conversation)
+* into {@link SheetComment}s. Each entry is one message (replies share the `ref`);
+* `personId` resolves through `persons`. Entries are returned in document order so
+* a thread reads top to bottom.
+*
+* @param data    The threaded-comments part bytes.
+* @param persons The `id → displayName` map from {@link parsePersons}.
+*/
 function parseThreadedComments(data, persons) {
 	const root = asObject(parser.parse(decoder.decode(data))["ThreadedComments"]);
 	if (!root) return [];

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 ?? [];