@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/io/xlsx/worksheet-xml.js

@@ -1,9 +1,3 @@
-// Worksheet serialisation: a Worksheet model into its `xl/worksheets/sheetN.xml` part and the sheet's
-// rels part. Owns the row/cell renderer the streaming writer also drives, and orchestrates the whole
-// sheet body — the print/page/view/protection blocks live in `sheet-properties.ts`, shared-formula
-// planning in `shared-formulas.ts`, each imported here rather than duplicated. Table *parts*
-// (`xl/tables/tableN.xml`) are `tables.ts`'s concern, alongside their reader — this module only wires
-// the sheet's `<tableParts>` back-references to them.
 import { decodeRange, encodeAddress, MAX_COLUMN } from '../../core/address.js';
 import { DEFAULT_DATE_NUMFMT, dateToSerial } from '../../core/date.js';
 import { mangleFormula } from '../../core/formula.js';
@@ -22,19 +16,11 @@ import { richTextRunsXml } from './rich-text.js';
 import { planSharedFormulas } from './shared-formulas.js';
 import { autoFilterXml, headerFooterXml, pageBreaksXml, pageMarginsXml, pageSetupXml, printOptionsXml, sheetProtectionXml, sheetPrXml, sheetViewsXml, } from './sheet-properties.js';
 import { x14Ext } from './x14-ext.js';
-/**
- * The used-cell extent of a sheet — the top-left/bottom-right grid bounds that fold into the
- * `<dimension>`. Rows carrying only formatting (a row height, an outline level) do not extend the
- * used range, matching how Excel records `<dimension>`, so {@link add} ignores them. A fresh extent
- * holds the `Infinity`/`-Infinity` sentinels; {@link isEmpty} reports that no used cell has been seen.
- */
 export class Extent {
     top = Infinity;
     left = Infinity;
     bottom = -Infinity;
     right = -Infinity;
-    // Seed from a prior extent (the rows a streaming writer already flushed and evicted) so the buffered
-    // pass folds its live rows onto the same bounds; unseeded, it starts empty.
     constructor(seed) {
         if (seed) {
             this.top = seed.top;
@@ -43,12 +29,9 @@ export class Extent {
             this.right = seed.right;
         }
     }
-    /** Whether no used cell has been folded in yet — the sheet's dimension is then the lone cell `A1`. */
     get isEmpty() {
         return this.bottom === -Infinity;
     }
-    /** Fold a rendered row's used-column span into the extent. `minCol` is `Infinity` when the row
-     * carried no cells (only formatting), which extends nothing. */
     add(row, minCol, maxCol) {
         if (minCol === Infinity)
             return;
@@ -63,18 +46,9 @@ export class Extent {
     }
 }
 export function worksheetXml(sheet, tables, styles, references, hyperlinks, sharedStrings, active, flushed) {
-    // A merge overlapping a table is Excel-invalid geometry; reject it before serialising
-    // rather than emit a package a consumer repairs on open.
     validateMerges(sheet);
     const columnDefaults = buildColumnDefaults(sheet);
-    // A cell filled from a shared formula is written as a master (seeding the group) or a clone
-    // (referencing it by shared index); resolve every such role before the row loop so each cell knows
-    // how to serialise its `<f>`. This also validates the master/clone geometry, throwing if a clone
-    // precedes its master or its master carries no formula.
     const sharedRoles = planSharedFormulas(sheet);
-    // A fully-hidden outline group's collapse toggle belongs on its summary row; derive that set once
-    // so the row loop can stamp it even onto a summary row that carries no properties of its own. The
-    // same pass yields the sheet's deepest row outline level for `<sheetFormatPr>`.
     const rowOutline = scanRowOutline(sheet);
     const collapsedSummaries = rowOutline.collapsedSummaries;
     const context = {
@@ -85,8 +59,6 @@ export function worksheetXml(sheet, tables, styles, references, hyperlinks, shar
         collapsedSummaries,
     };
     const liveRows = [];
-    // Seed the used-cell extent with any rows the streaming writer already serialised and evicted, so
-    // the dimension spans both them and the live rows below.
     const extent = new Extent(flushed?.extent);
     for (const entry of sheet.rows()) {
         const { xml, minCol, maxCol } = renderRow(entry, context);
@@ -98,9 +70,6 @@ export function worksheetXml(sheet, tables, styles, references, hyperlinks, shar
     const dimensionRef = extent.isEmpty
         ? 'A1'
         : `${encodeAddress(extent.left, extent.top)}:${encodeAddress(extent.right, extent.bottom)}`;
-    // Merge the streaming writer's pre-rendered rows with the live ones into ascending row order — a
-    // flushed row can carry any number, and rows may be committed out of order. The buffered path has no
-    // flushed rows, so it skips the merge and its sort entirely.
     const orderedRows = flushed
         ? [...flushed.rows, ...liveRows].sort((a, b) => a.number - b.number)
         : liveRows;
@@ -113,75 +82,40 @@ export function worksheetXml(sheet, tables, styles, references, hyperlinks, shar
         sheetViewsXml(sheet.view, active) +
         sheetFormatPr(sheet.properties, {
             col: maxColumnOutlineLevel(sheet),
-            // A streamed sheet's flushed rows are gone from the model; their deepest level rides along on
-            // the flush record so the header still reports the whole sheet's outline.
             row: Math.max(rowOutline.maxLevel, flushed?.maxRowOutlineLevel ?? 0),
         }) +
         colsXml(sheet, styles) +
         sheetData +
         sheetProtectionXml(sheet.protection) +
-        // CT_Worksheet order: <autoFilter> follows <sheetProtection> (and the scenarios block) and
-        // precedes <mergeCells>. Its `_FilterDatabase` companion is emitted in the workbook part.
         autoFilterXml(sheet.autoFilter) +
         mergeCellsXml(sheet.merges) +
-        // CT_Worksheet order: <conditionalFormatting> blocks follow <mergeCells>, then <dataValidations>,
-        // then <hyperlinks> — all precede the print settings.
         conditionalFormattingsXml(sheet.conditionalFormattings, styles) +
         dataValidationsXml(sheet.dataValidations) +
         hyperlinksXml(hyperlinks) +
-        // CT_Worksheet order: <printOptions> precedes <pageMargins>, which precedes <pageSetup>.
         printOptionsXml(sheet.printOptions) +
         pageMarginsXml(sheet.pageMargins) +
         pageSetupXml(sheet.pageSetup, references.printerSettingsRelId) +
         headerFooterXml(sheet.headerFooter) +
-        // CT_Worksheet order: <rowBreaks> follows <headerFooter>, <colBreaks> follows <rowBreaks>, and
-        // both precede the drawing block.
         pageBreaksXml(sheet.rowBreaks, 'rowBreaks') +
         pageBreaksXml(sheet.columnBreaks, 'colBreaks') +
-        // Schema order near the tail: <drawing> (the images), then <legacyDrawing> (the VML holding the
-        // note boxes), then <legacyDrawingHF> (a preserved header/footer image's VML), then <picture>
-        // (the sheet background), then <tableParts>.
         refElement('drawing', references.drawingRelId) +
         refElement('legacyDrawing', references.legacyDrawingRelId) +
         refElement('legacyDrawingHF', references.legacyDrawingHFRelId) +
         refElement('picture', references.backgroundRelId) +
         tablePartsXml(tables) +
-        // `<extLst>` is the final child of CT_Worksheet and a worksheet may carry at most one. Both the
-        // x14 conditional-formatting extensions (data-bar gradient/negative-fill/axis) and the extended
-        // (x14) data validations ride inside it as sibling `<ext>` blocks — so they are gathered here into
-        // a single `<extLst>` rather than each emitting its own.
         worksheetExtLstXml(sheet, references.slicerRelIds) +
         '</worksheet>');
 }
-/**
- * A column's style facets are defaults its cells inherit unless they override them; the writer
- * composes each cell's full style up front (cell over row over column, per facet) so a cell that
- * overrides one facet still carries the column's others, rather than silently dropping them. Frozen
- * once by the streaming writer at its first flush so every eagerly-rendered row sees the same defaults.
- */
 export function buildColumnDefaults(sheet) {
     const columnDefaults = new Map();
-    // `columns()` yields only columns that carry a format record, so the fallback is unreachable —
-    // it is here because the handle's `properties` is honestly optional, not because a defined
-    // column can lack one.
     for (const { index, properties } of sheet.columns())
         columnDefaults.set(index, properties ?? {});
     return columnDefaults;
 }
-/**
- * Serialise one row to its `<row>` element, or '' when the row has neither data nor its own
- * formatting. Returns the used-column bounds (`Infinity`/`-Infinity` when nothing was rendered) so a
- * caller can fold them into the sheet dimension. Shared by the buffered sheet pass and the streaming
- * writer's eager flush, so both emit byte-identical rows.
- */
 export function renderRow(entry, ctx) {
     const { number, cells, properties } = entry;
-    // A cell earns a <c> element if it holds a value OR carries its own style: a formatted-but-empty
-    // cell (a fill/border on a null value) is a real cell to Excel, and dropping it would lose the
-    // formatting. A cell with neither is inherited from its row/column and needs no element of its own.
     const rendered = cells.filter((cell) => cell.value !== null || hasOwnStyle(cell));
     const attrs = rowAttrs(properties, ctx.styles, ctx.collapsedSummaries.has(number));
-    // A row with neither data nor its own formatting has nothing to serialise.
     if (rendered.length === 0 && attrs === '')
         return { xml: '', minCol: Infinity, maxCol: -Infinity };
     const rowFill = properties?.fill;
@@ -201,28 +135,18 @@ export function renderRow(entry, ctx) {
     }
     return { xml: `<row r="${number}"${attrs}>${cellsXml}</row>`, minCol, maxCol };
 }
-// Compose a cell's full style by resolving each facet cell-over-row-over-column, so a cell that
-// overrides one facet still carries the row's fill and the column's other facets rather than silently
-// dropping them — the per-facet precedence Excel applies. The row contributes only a fill today;
-// quote-prefix and the named-style link are cell-only, with no row/column default to inherit.
 function composeCellStyle(cell, rowFill, colDef) {
     return {
         fill: cell.fill ?? rowFill ?? colDef?.fill,
-        // A bare Date carries no format of its own, so it renders as a raw serial and reads back as a
-        // number unless we apply a date format. An explicit cell/column format wins.
         numFmt: cell.numFmt ?? colDef?.numFmt ?? dateDefaultNumFmt(cell.value),
         font: cell.font ?? colDef?.font,
         border: cell.border ?? colDef?.border,
         alignment: cell.alignment ?? colDef?.alignment,
         protection: cell.protection ?? colDef?.protection,
         quotePrefix: cell.quotePrefix,
-        // Preserved so a round-trip keeps the cell tied to its named style rather than flattening it into
-        // a purely-direct format.
         xfId: cell[NAMED_STYLE_ID],
     };
 }
-// Assemble the worksheet's single `<extLst>` from every x14 extension the sheet carries, or '' when it
-// carries none. Each producer returns a bare `<ext>` so they compose without nesting an `<extLst>`.
 function worksheetExtLstXml(sheet, slicerRelIds) {
     const exts = [
         conditionalFormattingsExtXml(sheet.conditionalFormattings),
@@ -231,17 +155,12 @@ function worksheetExtLstXml(sheet, slicerRelIds) {
     ].filter((ext) => ext !== '');
     return exts.length === 0 ? '' : `<extLst>${exts.join('')}</extLst>`;
 }
-// The worksheet-body `<x14:slicerList>` extension that reconnects a sheet to its preserved slicer
-// parts. Each `<x14:slicer>` names the sheet-local relationship id its slicer rel was re-emitted under,
-// so the wiring stays consistent even though the id is reassigned on write. '' when the sheet has none.
 function slicerListExtXml(slicerRelIds) {
     if (slicerRelIds.length === 0)
         return '';
     const slicers = slicerRelIds.map((relId) => `<x14:slicer r:id="${relId}"/>`).join('');
     return x14Ext(SLICER_LIST_EXT_URI, `<x14:slicerList>${slicers}</x14:slicerList>`);
 }
-// Excel forbids a merged range from intersecting a formatted table; such a file opens as
-// corrupt. The writer is the OOXML gatekeeper for this cross-feature geometry conflict.
 function validateMerges(sheet) {
     if (sheet.merges.length === 0 || sheet.tables.length === 0)
         return;
@@ -269,9 +188,6 @@ function mergeCellsXml(merges) {
         .join('');
     return `<mergeCells count="${merges.length}">${cells}</mergeCells>`;
 }
-// A tail reference element (`<drawing r:id="…"/>` and its `<legacyDrawing>`/`<legacyDrawingHF>`/
-// `<picture>` siblings) wiring the sheet to a part by relationship id, or '' when the sheet carries no
-// part of that kind — each such id is null then.
 function refElement(tag, relId) {
     return relId === null ? '' : `<${tag} r:id="${relId}"/>`;
 }
@@ -284,8 +200,6 @@ function tablePartsXml(tables) {
 export function worksheetRelsXml(tables, drawing, comments, threadedComments, printerSettings, background, hyperlinks, preservedReferences, pivots) {
     const rels = [
         ...tables.map(({ relId, number }) => relationship(relId, REL.table, `../tables/table${number}.xml`)),
-        // A pivot table hosted on this sheet is reached by a relationship of type pivotTable; Excel
-        // discovers the pivot from the rels part, so the sheet body itself carries no reference to it.
         ...pivots.map((pivot) => relationship(pivot.sheetRelId, REL.pivotTable, `../pivotTables/pivotTable${pivot.number}.xml`)),
         ...(drawing === null
             ? []
@@ -296,8 +210,6 @@ export function worksheetRelsXml(tables, drawing, comments, threadedComments, pr
                 relationship(comments.vmlRelId, REL.vmlDrawing, `../drawings/vmlDrawing${comments.number}.vml`),
                 relationship(comments.commentsRelId, REL.comments, `../comments${comments.number}.xml`),
             ]),
-        // A threaded-comment part, like a pivot table, is reached by relationship alone — no worksheet element
-        // names it, so this relationship is the only thing that makes Excel look for the conversation.
         ...(threadedComments === null
             ? []
             : [
@@ -313,11 +225,7 @@ export function worksheetRelsXml(tables, drawing, comments, threadedComments, pr
             : [
                 relationship(background.relId, REL.image, `../media/image${background.mediaNumber}.${background.extension}`),
             ]),
-        // A preserved reference targets its entry part's new (package-absolute) path; a worksheet always
-        // lives under `xl/worksheets/`, so the target is that path made relative to that directory.
         ...preservedReferences.map((reference) => relationship(reference.relId, reference.relType, escapeAttr(relativePartPath('xl/worksheets/sheet1.xml', reference.entryPath)))),
-        // An external hyperlink's target is a URL outside the package, so its relationship carries
-        // TargetMode="External". Internal links have no relId and contribute nothing here.
         ...hyperlinks
             .filter((link) => link.relId !== undefined && link.target !== undefined)
             .map((link) => relationship(link.relId, REL.hyperlink, escapeAttr(link.target), {
@@ -326,21 +234,13 @@ export function worksheetRelsXml(tables, drawing, comments, threadedComments, pr
     ];
     return relationshipsPart(rels);
 }
-// Excel's standard row height in points, emitted as the `defaultRowHeight` when the sheet does not
-// override it so a reader sees the same baseline Excel would write.
 const DEFAULT_ROW_HEIGHT = 15;
-// `<sheetFormatPr>` carries the sheet's grid defaults and, when the sheet groups anything, the depth
-// of its deepest outline. A consumer sizes the outline bars from those depths — the strips that sit
-// above the column headers and left of the row headers — so a grouped sheet that omits them lays its
-// grid out with no room reserved for a bar it then has to draw. Both are omitted at zero, as Excel
-// does, so an ungrouped sheet stays byte-clean.
 function sheetFormatPr(properties, outlineLevel) {
     const rowHeight = properties.defaultRowHeight ?? DEFAULT_ROW_HEIGHT;
     let attrs = ` defaultRowHeight="${numberText(rowHeight)}"`;
     if (properties.defaultColWidth !== undefined) {
         attrs += ` defaultColWidth="${numberText(properties.defaultColWidth)}"`;
     }
-    // A non-standard default row height is only honoured by Excel when customHeight is set.
     if (properties.defaultRowHeight !== undefined)
         attrs += ' customHeight="1"';
     if (outlineLevel.col > 0)
@@ -349,9 +249,6 @@ function sheetFormatPr(properties, outlineLevel) {
         attrs += ` outlineLevelRow="${outlineLevel.row}"`;
     return `<sheetFormatPr${attrs}/>`;
 }
-// The deepest column outline level the sheet declares — the `outlineLevelCol` its `<sheetFormatPr>`
-// reports. A column past XFD contributes nothing: {@link colsXml} drops it as out-of-range, so its
-// group would have no `<col>` to sit on.
 function maxColumnOutlineLevel(sheet) {
     let max = 0;
     for (const column of sheet.columns()) {
@@ -362,19 +259,11 @@ function maxColumnOutlineLevel(sheet) {
     return max;
 }
 function colsXml(sheet, styles) {
-    // Runs of adjacent columns that carry identical definitions are coalesced into a single
-    // `<col min max>` span — Excel writes columns this way, and it keeps the part compact for a
-    // sheet whose columns share a width or outline level. A gap in the indices or any difference
-    // in the emitted attributes breaks the run.
     const runs = [];
     for (const { index, properties } of sheet.columns()) {
-        // OOXML has no column past XFD (16384); a definition beyond it is corrupt to Excel,
-        // so drop it rather than emit an out-of-range <col> range.
         if (index > MAX_COLUMN)
             continue;
         const body = colBody(properties ?? {}, styles);
-        // A <col> with no width, visibility, or style says nothing; omit it entirely. That also covers
-        // the column with no format record at all, which `columns()` does not in fact yield.
         if (body === null)
             continue;
         const last = runs[runs.length - 1];
@@ -390,9 +279,6 @@ function colsXml(sheet, styles) {
     const cols = runs.map((run) => `<col min="${run.min}" max="${run.max}"${run.body}/>`).join('');
     return `<cols>${cols}</cols>`;
 }
-// The attributes of a `<col>` sans its `min`/`max` span (each with a leading space), or `null` when
-// the column declares nothing worth emitting. Two columns with the same body are interchangeable, so
-// the body doubles as the equivalence key that {@link colsXml} coalesces adjacent runs by.
 function colBody(properties, styles) {
     let attrs = '';
     let meaningful = false;
@@ -412,9 +298,6 @@ function colBody(properties, styles) {
         attrs += ' collapsed="1"';
         meaningful = true;
     }
-    // The column's style facets are carried as its own `<col>` style; its populated cells inherit
-    // them via the composition above, and this `style` makes Excel apply them to the column's empty
-    // cells too.
     const style = styles.styleId({
         fill: properties.fill,
         numFmt: properties.numFmt,
@@ -440,25 +323,13 @@ function rowAttrs(properties, styles, collapsedSummary) {
     if (properties.outlineLevel !== undefined && properties.outlineLevel > 0) {
         attrs += ` outlineLevel="${properties.outlineLevel}"`;
     }
-    // The collapse toggle is set explicitly by the author, or derived onto a summary row whose whole
-    // detail group is hidden (see {@link collapsedSummaryRows}). It rides the summary row, never the
-    // detail rows.
     if (properties.collapsed || collapsedSummary)
         attrs += ' collapsed="1"';
-    // A row-level fill is a default format for the row's cells; customFormat="1" is what makes
-    // Excel honour the row's `s`, and a cell without its own `s` then inherits it.
     const style = styles.styleId({ fill: properties.fill });
     if (style !== 0)
         attrs += ` s="${style}" customFormat="1"`;
     return attrs;
 }
-// A collapsed outline group is two coordinated facts: its detail rows carry outlineLevel and are
-// hidden, AND the summary row that terminates the group carries `collapsed`. Authors typically set
-// only outlineLevel + hidden on the detail rows, so the summary flag is derived here rather than
-// demanded of the caller: a row is a collapsed summary iff its adjacent detail run — the contiguous
-// higher-outline-level rows on the summary side — is non-empty and every row in it is hidden.
-// Placement follows the sheet's summaryBelow flag (Excel's default is summary below the detail); the
-// walk stops at the first row of level <= the summary's own, so a gap or a boundary ends the group.
 function scanRowOutline(sheet) {
     const level = new Map();
     const hidden = new Map();
@@ -488,9 +359,6 @@ function scanRowOutline(sheet) {
     }
     return { collapsedSummaries, maxLevel };
 }
-// A valid Date — whether the cell's own value or a formula's cached result — with no format of its
-// own gets the default date format so it renders and reads back as a date rather than a bare serial.
-// An Invalid Date and every non-date value contribute nothing here.
 function dateDefaultNumFmt(value) {
     const date = value instanceof Date
         ? value
@@ -507,16 +375,11 @@ function cellXml(cell, style, shared, sharedStrings) {
     if (formula !== undefined)
         return formula;
     if (value instanceof Date) {
-        // An Invalid Date (new Date(NaN)) has no serial; keep the cell (and its style) but emit no
-        // value rather than throwing, so one bad date never takes down the whole sheet's export.
         if (Number.isNaN(value.getTime()))
             return `<c r="${ref}"${s}/>`;
         return `<c r="${ref}"${s}><v>${numberText(dateToSerial(value))}</v></c>`;
     }
     if (typeof value === 'number') {
-        // A non-finite number (NaN, ±Infinity) has no OOXML representation; keep the cell and its style
-        // but emit no value rather than a bare "NaN"/"Infinity" token — the same graceful degradation an
-        // Invalid Date gets, so one bad value never corrupts the sheet or takes down the whole export.
         if (!Number.isFinite(value))
             return `<c r="${ref}"${s}/>`;
         return `<c r="${ref}"${s}><v>${numberText(value)}</v></c>`;
@@ -525,46 +388,30 @@ function cellXml(cell, style, shared, sharedStrings) {
         return `<c r="${ref}"${s} t="b"><v>${value ? 1 : 0}</v></c>`;
     }
     if (typeof value === 'string') {
-        // With shared strings on, the cell holds only the pool index (`t="s"`); otherwise the text
-        // lives inline in the cell. Both decode to the same string on read.
         if (sharedStrings !== null) {
             return `<c r="${ref}"${s} t="s"><v>${sharedStrings.intern(value)}</v></c>`;
         }
         return `<c r="${ref}"${s} t="inlineStr"><is>${textElement(value)}</is></c>`;
     }
     if (isRichTextValue(value)) {
-        // With shared strings on, rich text is pooled as a rich `<si>` (the cell holds only its index);
-        // otherwise the runs live inline. Both decode back to the same runs on read.
         if (sharedStrings !== null) {
             return `<c r="${ref}"${s} t="s"><v>${sharedStrings.intern(value)}</v></c>`;
         }
         return `<c r="${ref}"${s} t="inlineStr"><is>${richTextRunsXml(value.richText)}</is></c>`;
     }
     if (isHyperlinkValue(value)) {
-        // The cell holds only the visible label; the link itself rides in the sheet's <hyperlinks>.
-        // The label is either a plain string or rich text, serialised the same way a cell value of
-        // that kind would be.
         const label = typeof value.text === 'string'
             ? textElement(value.text)
             : richTextRunsXml(value.text.richText);
         return `<c r="${ref}"${s} t="inlineStr"><is>${label}</is></c>`;
     }
     if (isErrorValue(value)) {
-        // An error literal serialises under t="e" with its code as the value. The codes are a closed
-        // set of canonical spellings (see ERROR_CODES) with no XML-special characters, so no escaping.
         return `<c r="${ref}"${s} t="e"><v>${value.error}</v></c>`;
     }
-    // A null value only reaches here for a formatted-but-empty cell (the row loop keeps it for its
-    // style); emit the styled cell with no <v>, exactly how Excel stores a formatted blank.
     if (value === null)
         return `<c r="${ref}"${s}/>`;
-    // Every ValueType kind is served by an arm above (a formula routes through its own writer), so
-    // this is unreachable — it exists because the union is not exhaustively narrowed here.
     throw new InternalError(`writing a ${detectValueType(value)} cell value has no arm — every CellValue kind is handled above`);
 }
-// Whether a cell carries any style facet of its own — the reason to serialise it even when empty.
-// A note is not a style: it lives in the comments part, not the cell's <c> element, so it does not
-// count here. Row/column-inherited formatting is likewise excluded; only the cell's own facets do.
 function hasOwnStyle(cell) {
     return (cell.fill !== undefined ||
         cell.numFmt !== undefined ||
@@ -575,13 +422,7 @@ function hasOwnStyle(cell) {
         cell.quotePrefix === true ||
         cell[NAMED_STYLE_ID] !== undefined);
 }
-// Serialise a formula cell — a shared-formula master or clone, a What-If data table, or a plain
-// formula — into its `<c>` element, or return undefined when the value is not a formula so `cellXml`
-// falls through to its value dispatch.
 function cellFormulaXml(ref, s, value, shared) {
-    // A shared-formula master seeds the group with its formula text under `t="shared" ref si`; a clone
-    // carries no text of its own, only a back-reference to the master's `si`. Its cached result still
-    // travels with the cell.
     if (shared !== undefined) {
         if (shared.ref !== undefined && isFormulaValue(value)) {
             const f = `<f t="shared" ref="${shared.ref}" si="${shared.si}">${escapeText(mangleFormula(value.formula))}</f>`;
@@ -591,9 +432,6 @@ function cellFormulaXml(ref, s, value, shared) {
         return formulaBodyXml(ref, s, `<f t="shared" si="${shared.si}"/>`, result);
     }
     if (isDataTableFormulaValue(value)) {
-        // A data-table formula carries no expression text — only its declaration attributes — which we
-        // re-emit verbatim so a read-modify-write cycle preserves the What-If kind the library never
-        // evaluates. The cached result travels as any formula result does.
         const attrs = `ref="${escapeAttr(value.ref)}"` +
             ` dt2D="${value.dataTable2D ? 1 : 0}"` +
             ` dtr="${value.dataTableRow ? 1 : 0}"` +
@@ -606,13 +444,7 @@ function cellFormulaXml(ref, s, value, shared) {
     }
     return undefined;
 }
-// Wrap a prepared `<f>` element (a plain formula, or a shared master/slave `<f>`) with the cell
-// element and its cached result, typing the cell by the result's kind exactly as a bare value of that
-// kind would be.
 function formulaBodyXml(ref, s, f, result) {
-    // A non-finite cached result (a `1/0` that reached the model as Infinity/NaN) has no OOXML
-    // representation; keep the formula but cache no value rather than emit a bare "NaN" — the same
-    // graceful degradation a bare non-finite cell and an Invalid Date result get.
     if (result === undefined || (typeof result === 'number' && !Number.isFinite(result))) {
         return `<c r="${ref}"${s}>${f}</c>`;
     }
@@ -626,18 +458,12 @@ function formulaBodyXml(ref, s, f, result) {
         return `<c r="${ref}"${s} t="str">${f}<v>${escapeText(result)}</v></c>`;
     }
     if (isErrorValue(result)) {
-        // A formula that evaluated to an error caches its code under t="e", exactly as a bare error
-        // cell does — the reader's decodeResult mirrors decodeValue for this case.
         return `<c r="${ref}"${s} t="e">${f}<v>${result.error}</v></c>`;
     }
     if (result instanceof Date) {
-        // A date-valued result caches its serial exactly as a bare date cell stores its value; the
-        // cell's date number format (applied when its style is composed) is what makes both read back as
-        // a Date. An Invalid Date has no serial, so cache no result rather than emit NaN.
         if (Number.isNaN(result.getTime()))
             return `<c r="${ref}"${s}>${f}</c>`;
         return `<c r="${ref}"${s}>${f}<v>${numberText(dateToSerial(result))}</v></c>`;
     }
-    // Every FormulaResult kind is handled above; this guards a value that reached here past the model.
     throw new InternalError('writing a non-primitive formula result has no arm — every FormulaResult kind is handled above');
 }