@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/io/xlsx/color-xml.d.ts

@@ -0,0 +1,6 @@
+import type { Color } from '../../core/style.ts';
+/** Serialise a {@link Color} as the attribute list a `<color>`-shaped element carries. */
+export declare function colorAttrs(color: Color): string;
+export declare function parseColor(attrs: {
+    readonly [k: string]: string;
+}): Color;

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

@@ -0,0 +1,42 @@
+import { AuthoringError } from '../../errors.js';
+function normalizeArgb(argb) {
+    const hex = argb.startsWith('#') ? argb.slice(1) : argb;
+    const rgb = hex.length === 6 ? `FF${hex}` : hex;
+    if (!/^[0-9a-fA-F]{8}$/.test(rgb)) {
+        throw new AuthoringError(`Invalid ARGB colour ${JSON.stringify(argb)}: expected 6 or 8 hexadecimal digits`);
+    }
+    return rgb;
+}
+export function colorAttrs(color) {
+    const parts = [];
+    if (color.argb !== undefined)
+        parts.push(`rgb="${normalizeArgb(color.argb)}"`);
+    if (color.theme !== undefined)
+        parts.push(`theme="${color.theme}"`);
+    if (color.tint !== undefined)
+        parts.push(`tint="${color.tint}"`);
+    if (color.indexed !== undefined)
+        parts.push(`indexed="${color.indexed}"`);
+    return parts.join(' ');
+}
+export function parseColor(attrs) {
+    const color = {};
+    if (attrs.rgb !== undefined)
+        color.argb = attrs.rgb;
+    if (attrs.theme !== undefined) {
+        const theme = Number(attrs.theme);
+        if (Number.isInteger(theme))
+            color.theme = theme;
+    }
+    if (attrs.tint !== undefined) {
+        const tint = Number(attrs.tint);
+        if (Number.isFinite(tint))
+            color.tint = tint;
+    }
+    if (attrs.indexed !== undefined) {
+        const indexed = Number(attrs.indexed);
+        if (Number.isInteger(indexed))
+            color.indexed = indexed;
+    }
+    return color;
+}

package/dist/io/xlsx/comments.js

@@ -1,49 +1,13 @@
-// Cell comments — the `xl/comments{n}.xml` part, its `xl/drawings/vmlDrawing{n}.vml` companion, and the
-// reader that maps a comment back onto its cell.
-//
-// A comment is anchored to a cell by A1 reference and rendered by Excel as a floating box. The box's
-// geometry lives in a legacy VML drawing (the pre-DrawingML shape format Excel still requires here);
-// the text lives in the comments part. Both are emitted together — a comments part with no matching
-// `<legacyDrawing>`/VML reads as text but renders nothing, so we never split them.
-//
-// Two different things share this one wire form:
-//   • a user's **note** (`cell.note`) — a single anonymous annotation, the whole of what the part held
-//     before 2018;
-//   • the legacy **fallback** Excel writes beside every modern threaded comment (see
-//     `threaded-comments.ts`), so a pre-2018 reader still sees the conversation. Its text is a fixed
-//     boilerplate wrapping a copy of the thread, and its author is a synthetic `tc={headId}` entry.
-//
-// That `tc=` author and the comment's `xr:uid` are how Excel binds a cell back to its thread — not
-// decoration. Verified against desktop Excel: a package whose threadedComment part, persons registry,
-// relationships and content types all survive intact still reads back as ordinary notes with zero
-// threads once those two are lost. So the fallback is *derived from the thread model* on write and
-// *suppressed on read*, rather than round-tripped as a plain note.
 import { decodeAddress } from '../../core/address.js';
 import { escapeAttr, escapeText, textElement, XML_DECLARATION } from '../../xml/xml.js';
 import { localName, parseXml } from '../../xml/xml-read.js';
 import { MARKUP_COMPATIBILITY_NS, REVISION_NS, SPREADSHEETML_NS } from './namespaces.js';
-/**
- * Gather every comment a sheet must write: its cells' notes, plus one legacy fallback per conversation
- * in `threads`. A comment anchors to its cell regardless of the cell's value, so a note (or a thread) on
- * an otherwise-empty cell is collected too.
- *
- * `threads` is the conversations the *package* will carry, not simply the ones the sheet holds — the
- * caller decides, because a fallback beside a thread whose `threadedComment` part is missing is worse
- * than no fallback at all: verified against desktop Excel, such a comment shows as neither a thread nor
- * a note, so the text disappears entirely.
- *
- * Ordered by cell, row-major, the way Excel writes the list — so a fallback lands interleaved among the
- * notes rather than appended after them, and the VML shapes follow the same order.
- */
 export function collectComments(sheet, threads) {
     const fallbacks = threadFallbacks(threads);
     const anchored = new Set(fallbacks.map((fallback) => fallback.ref));
     const comments = [...fallbacks];
     for (const { cells } of sheet.rows()) {
         for (const cell of cells) {
-            // Excel refuses to put a note and a thread on one cell, so a file carrying both (only a foreign
-            // generator or a hand-edit makes one) is written back as the thread alone: two comments on one ref
-            // is a shape Excel repairs by dropping both, which would lose the conversation as well as the note.
             if (cell.note === undefined || anchored.has(cell.address))
                 continue;
             comments.push({ ref: cell.address, row: cell.row, col: cell.col, text: cell.note });
@@ -51,8 +15,6 @@ export function collectComments(sheet, threads) {
     }
     return comments.sort((a, b) => a.row - b.row || a.col - b.col);
 }
-// One legacy fallback per conversation, keyed to the thread head whose id binds it. A thread with no
-// messages has nothing to write and no id to bind by, so it contributes none.
 function threadFallbacks(threads) {
     const fallbacks = [];
     for (const thread of threads) {
@@ -64,31 +26,15 @@ function threadFallbacks(threads) {
     }
     return fallbacks;
 }
-// The boilerplate Excel puts in front of every fallback, captured verbatim from an Excel-authored file.
-// It is what a pre-2018 reader shows the user, so it is reproduced exactly rather than paraphrased.
 const FALLBACK_PREAMBLE = '[Threaded comment]\n\nYour version of Excel allows you to read this threaded comment; however, any ' +
     'edits to it will get removed if the file is opened in a newer version of Excel. Learn more: ' +
     'https://go.microsoft.com/fwlink/?linkid=870924\n\n';
-// A whole conversation flattened into the one comment a pre-2018 reader can render: the opening message
-// under `Comment:`, then each reply under its own `Reply:`, every body indented four spaces. Verified
-// against desktop Excel for a thread with three replies — `Reply:` repeats per reply rather than the
-// replies being joined under one heading.
 function fallbackText(thread) {
     const [head, ...replies] = thread.comments;
     const body = replies.map((reply) => `\nReply:\n    ${reply.text}`).join('');
     return `${FALLBACK_PREAMBLE}Comment:\n    ${head?.text ?? ''}${body}`;
 }
-// `xr:uid` lives in the 2014 revision namespace, declared `mc:Ignorable` exactly as Excel declares it so
-// a consumer that does not know the prefix skips the attribute instead of rejecting the part.
 const REVISION_NS_ATTRS = ` xmlns:mc="${MARKUP_COMPATIBILITY_NS}" mc:Ignorable="xr" xmlns:xr="${REVISION_NS}"`;
-/**
- * The `xl/comments{n}.xml` part.
- *
- * Authors are laid out the way Excel lays them out: one synthetic `tc={headId}` entry per threaded
- * conversation first, then a single anonymous author shared by every note (the model carries no note
- * author). Each comment points at its own author by index, and a fallback additionally carries the
- * `xr:uid` naming its thread — the pair that keeps Excel treating the cell as threaded.
- */
 export function commentsXml(comments) {
     const authorIdByThreadId = new Map();
     for (const { threadId } of comments) {
@@ -116,7 +62,6 @@ export function commentsXml(comments) {
         `<commentList>${list}</commentList>` +
         '</comments>');
 }
-// VML namespaces and the one shape type (a text box) every comment reuses.
 const VML_HEADER = '<xml xmlns:v="urn:schemas-microsoft-com:vml" ' +
     'xmlns:o="urn:schemas-microsoft-com:office:office" ' +
     'xmlns:x="urn:schemas-microsoft-com:office:excel">' +
@@ -124,11 +69,6 @@ const VML_HEADER = '<xml xmlns:v="urn:schemas-microsoft-com:vml" ' +
     '<v:shapetype id="_x0000_t202" coordsize="21600,21600" o:spt="202" ' +
     'path="m,l,21600r21600,l21600,xe"><v:stroke joinstyle="miter"/>' +
     '<v:path gradientshapeok="t" o:connecttype="rect"/></v:shapetype>';
-/** The `xl/drawings/vmlDrawing{n}.vml` companion: one hidden text-box shape per comment, in the same
- * order as the comments part. Anchor coordinates place the box a couple of cells down-and-right of its
- * owner; Excel refines them on open, so the values are a sensible starting geometry rather than a
- * pixel-exact layout. A thread's fallback shape is `ObjectType="Note"` like any other — Excel draws the
- * threaded-comment card itself and only needs the shape to exist. */
 export function vmlDrawingXml(comments) {
     const shapes = comments
         .map((comment, i) => {
@@ -148,18 +88,8 @@ export function vmlDrawingXml(comments) {
         .join('');
     return `${VML_HEADER}${shapes}</xml>`;
 }
-// A comment names its author by index into `<authors>`, so an empty entry must still occupy its slot —
-// presenting the self-closing `<author/>` an author-less file writes as an empty element gives it the
-// close that pushes it. Without this every later index would shift by one and a note could inherit a
-// thread's `tc=` author.
 const COMMENT_EMPTY_CLOSES = new Set(['author']);
-// The author string marking a comment as a thread's legacy fallback: `tc={headThreadId}`.
 const THREAD_AUTHOR_PREFIX = 'tc=';
-/**
- * Parse a `comments{n}.xml` part into a map of A1 reference → comment. Text runs within one comment are
- * concatenated; an author-name run is Excel's own convention and is not stripped, so a note reads back
- * as exactly the text that was written.
- */
 export function parseComments(xml) {
     const comments = new Map();
     const authors = [];
@@ -210,26 +140,12 @@ export function parseComments(xml) {
     }, { closeEmptyElements: COMMENT_EMPTY_CLOSES });
     return comments;
 }
-// A missing or non-numeric `authorId` indexes nothing, so `authors[NaN]` is undefined and the comment
-// reads as a plain note — the safe direction, since mistaking a note for a fallback would delete it.
 function threadIdOf(author) {
     if (author === undefined || !author.startsWith(THREAD_AUTHOR_PREFIX))
         return undefined;
     const id = author.slice(THREAD_AUTHOR_PREFIX.length);
     return id === '' ? undefined : id;
 }
-/**
- * Apply a parsed comments part onto a sheet's cells as notes, addressing each by its A1 reference.
- *
- * A thread's legacy fallback is not a note and does not become one: its text is boilerplate wrapping a
- * copy of the conversation, so surfacing it as `cell.note` hands the caller garbage — and on write it
- * would be re-emitted as a plain note, destroying the `tc=`/`xr:uid` binding and leaving Excel unable to
- * see the thread at all.
- *
- * Suppressed only for a conversation the reader actually holds: a file whose thread part is missing or
- * damaged has nothing else left, so there the boilerplate is kept rather than the content lost. Call
- * after the sheet's threads are restored, since that is what this reads to decide.
- */
 export function applyNotes(sheet, comments) {
     const headIds = new Set(sheet.commentThreads.flatMap((thread) => {
         const head = thread.comments[0];

package/dist/io/xlsx/conditional-formatting.d.ts

@@ -1,5 +1,5 @@
 import type { ConditionalFormatting } from '../../core/conditional-formatting.ts';
-import { type StyleRegistry } from './styles.ts';
+import type { StyleRegistry } from './styles.ts';
 /**
  * Serialise every conditional formatting on a sheet into its `<conditionalFormatting>` blocks, in
  * insertion order. Returns '' when the sheet has none. A rule missing a `priority` is assigned the

package/dist/io/xlsx/conditional-formatting.js

@@ -1,47 +1,18 @@
-// Serialising conditional formatting to the classic `<conditionalFormatting>` worksheet element.
-//
-// Each block names its target range(s) in a `sqref` attribute and holds one or more `<cfRule>`
-// children. A rule's shape depends on its type: a `dataBar`/`colorScale`/`iconSet` carries a scale
-// element (its `<cfvo>` anchors and colours), while a `cellIs`/`expression`/`top10`/… carries its
-// operands as `<formula>` children and points at a differential style by `dxfId`. A rule the library
-// does not model in depth still round-trips its attributes, so nothing is silently dropped on save.
-//
-// A data bar's richer facets — its gradient fill, its negative-value fill colour, its axis colour —
-// have no home in the classic `<dataBar>` element; Excel stores them only in the 2009 x14 extension.
-// So a data-bar rule carrying any of them is written twice: the classic element (its anchors and bar
-// colour, understood by every consumer) plus an `<x14:dataBar>` in the worksheet `<extLst>` carrying
-// the extras, the two linked by a shared id. The reader folds the extension back onto the classic
-// rule, so the gradient flag and the two extra colours survive a round-trip rather than being dropped.
 import { boolAttr, escapeAttr, escapeText, stripFormulaEquals } from '../../xml/xml.js';
 import { boolStrict, coerceNumericLiteral, localName, parseXml } from '../../xml/xml-read.js';
-// The x14/xm extension namespaces and ext-URI GUIDs are declared inline on the `<ext>` elements
-// exactly as Excel writes them, so no worksheet-root xmlns is needed. `CF_EXT_URI` scopes the
-// worksheet's x14 conditional formattings; `DATABAR_LINK_EXT_URI` scopes the `<x14:id>` link a
-// classic cfRule carries to name its extension.
+import { colorAttrs, parseColor } from './color-xml.js';
 import { CF_EXT_URI, DATABAR_LINK_EXT_URI, XM_NS } from './namespaces.js';
-import { colorAttrs, parseColor } from './styles.js';
 import { x14Ext } from './x14-ext.js';
-// Excel's default data bar when the author supplies none: a min/max anchor pair and its standard blue.
 const DEFAULT_DATABAR_CFVO = [{ type: 'min' }, { type: 'max' }];
 const DEFAULT_DATABAR_COLOR = { argb: 'FF638EC6' };
-// A data bar needs the x14 extension only when it carries a facet the classic element cannot express.
-// A plain data bar (anchors and bar colour alone) stays classic-only, so an unadorned rule never
-// fabricates an empty extension block.
 function needsDataBarExt(rule) {
     return (rule.gradient !== undefined ||
         rule.negativeFillColor !== undefined ||
         rule.axisColor !== undefined);
 }
-// The synthetic id linking a classic cfRule to its x14 extension. Excel uses a random GUID; any unique
-// token that matches on both ends works, so a deterministic per-sheet index keeps the output stable
-// and testable.
 function dataBarExtGuid(index) {
     return `{00000000-0000-0000-0000-${String(index + 1).padStart(12, '0')}}`;
 }
-// Assign every extended data bar its link id once, keyed by rule identity. The classic pass (which
-// emits the `<extLst>` link on the cfRule) and the extension pass (which emits the `<x14:cfRule id>`)
-// both read the id from this map, so the two ends of a link agree by construction — not by the two
-// passes happening to walk the rules in the same order. A rule absent from the map needs no extension.
 function dataBarExtLinks(formattings) {
     const links = new Map();
     let index = 0;
@@ -53,16 +24,8 @@ function dataBarExtLinks(formattings) {
     }
     return links;
 }
-// The three built-in visual rules. Each renders a built-in visual and carries no differential
-// style (so the write side skips the dxf), and each nests its `<color>` children differently (so
-// the read side, {@link ScaleKind}, tracks which one it is inside). This tuple drives both.
 const SCALE_KINDS = ['dataBar', 'colorScale', 'iconSet'];
 const SCALE_TYPES = new Set(SCALE_KINDS);
-/**
- * Serialise every conditional formatting on a sheet into its `<conditionalFormatting>` blocks, in
- * insertion order. Returns '' when the sheet has none. A rule missing a `priority` is assigned the
- * next free one, so the output always satisfies Excel's requirement that every cfRule carry one.
- */
 export function conditionalFormattingsXml(formattings, styles) {
     if (formattings.length === 0)
         return '';
@@ -70,13 +33,6 @@ export function conditionalFormattingsXml(formattings, styles) {
     const extLinks = dataBarExtLinks(formattings);
     return formattings.map((cf) => blockXml(cf, styles, priority, extLinks)).join('');
 }
-/**
- * The worksheet `<extLst>` `<ext>` carrying the x14 data-bar extensions, or '' when no data bar needs
- * one. Each extension's `<x14:cfRule id>` is read from the same {@link dataBarExtLinks} map the classic
- * pass uses for the `<x14:id>` its cfRule carries, so the two ends of a link always match. Emitted bare
- * (no `<extLst>` wrapper) so the worksheet serialiser can gather it into a single `<extLst>` beside the
- * data-validation extension.
- */
 export function conditionalFormattingsExtXml(formattings) {
     const extLinks = dataBarExtLinks(formattings);
     const items = [];
@@ -91,9 +47,6 @@ export function conditionalFormattingsExtXml(formattings) {
         return '';
     return x14Ext(CF_EXT_URI, `<x14:conditionalFormattings>${items.join('')}</x14:conditionalFormattings>`);
 }
-// One `<x14:conditionalFormatting>`: an `<x14:cfRule type="dataBar" id>` mirroring the classic anchors
-// as `<x14:cfvo>` and adding the facets the classic element cannot carry (gradient, negative-fill and
-// axis colours), with the target range in an `<xm:sqref>` child — the shape Excel writes.
 function x14DataBarXml(ref, rule, guid) {
     const cfvo = rule.cfvo && rule.cfvo.length > 0 ? rule.cfvo : DEFAULT_DATABAR_CFVO;
     const anchors = cfvo.map(x14CfvoXml).join('');
@@ -107,15 +60,12 @@ function x14DataBarXml(ref, rule, guid) {
         `<x14:dataBar${gradient}>${anchors}${negative}${axis}</x14:dataBar>` +
         `</x14:cfRule><xm:sqref>${escapeText(ref)}</xm:sqref></x14:conditionalFormatting>`);
 }
-// An x14 scale anchor. A `min`/`max` carries no value and self-closes; the rest wrap their value in an
-// `<xm:f>` (the extension form stores every anchor value as a formula).
 function x14CfvoXml(cfvo) {
     const type = escapeAttr(cfvo.type);
     if (cfvo.value === undefined)
         return `<x14:cfvo type="${type}"/>`;
     return `<x14:cfvo type="${type}"><xm:f>${escapeText(String(cfvo.value))}</xm:f></x14:cfvo>`;
 }
-// The `<extLst>` a classic data-bar cfRule carries to name its x14 extension by shared id.
 function cfRuleExtLinkXml(guid) {
     return `<extLst>${x14Ext(DATABAR_LINK_EXT_URI, `<x14:id>${guid}</x14:id>`)}</extLst>`;
 }
@@ -125,7 +75,6 @@ function blockXml(cf, styles, priority, extLinks) {
 }
 function ruleXml(rule, styles, priority, extLinks) {
     const p = rule.priority ?? priority.next;
-    // Keep the running counter ahead of any explicit priority so later auto-assigned ones stay unique.
     priority.next = Math.max(priority.next, p) + 1;
     const attrs = [`type="${escapeAttr(rule.type)}"`];
     const dxfId = resolveDxfId(rule, styles);
@@ -153,9 +102,6 @@ function ruleXml(rule, styles, priority, extLinks) {
     if (rule.stdDev !== undefined)
         attrs.push(`stdDev="${rule.stdDev}"`);
     let body = SCALE_TYPES.has(rule.type) ? scaleXml(rule) : formulaeXml(rule.formulae);
-    // A data bar with x14-only facets links to its extension by the id assigned in dataBarExtLinks; the
-    // extension itself rides in the worksheet <extLst>. The link is the cfRule's last child, after the
-    // dataBar. A rule absent from the map carries no extension.
     const extGuid = extLinks.get(rule);
     if (extGuid !== undefined)
         body += cfRuleExtLinkXml(extGuid);
@@ -163,9 +109,6 @@ function ruleXml(rule, styles, priority, extLinks) {
         ? `<cfRule ${attrs.join(' ')}/>`
         : `<cfRule ${attrs.join(' ')}>${body}</cfRule>`;
 }
-// A rule points at a differential style either by a preserved index read from a file (`dxfId`) or by
-// a style authored on the rule (interned here). The preserved index wins — it references the original
-// file's dxf table, which the writer re-emits verbatim. Scale rules never carry one.
 function resolveDxfId(rule, styles) {
     if (SCALE_TYPES.has(rule.type))
         return undefined;
@@ -187,19 +130,12 @@ function scaleXml(rule) {
         return colorScaleXml(rule);
     return iconSetXml(rule);
 }
-// A data bar states its low and high anchors and its bar colour. The minimal call (no cfvo, no colour)
-// gains Excel's own defaults — a min/max anchor pair and the standard blue — rather than an invalid
-// empty element. The gradient flag and the negative-fill/axis colours have no home in this classic
-// element; they ride in the x14 extension (see {@link conditionalFormattingsExtXml}), linked from the
-// cfRule that wraps this by a shared id.
 function dataBarXml(rule) {
     const cfvo = rule.cfvo && rule.cfvo.length > 0 ? rule.cfvo : DEFAULT_DATABAR_CFVO;
     const color = rule.color ?? DEFAULT_DATABAR_COLOR;
     const anchors = cfvo.map(cfvoXml).join('');
     return `<dataBar>${anchors}<color ${colorAttrs(color)}/></dataBar>`;
 }
-// A colour scale pairs each anchor with a colour; a missing colour list falls back to none, still a
-// well-formed (if plain) element.
 function colorScaleXml(rule) {
     const anchors = (rule.cfvo ?? []).map(cfvoXml).join('');
     const colors = (rule.colors ?? []).map((c) => `<color ${colorAttrs(c)}/>`).join('');
@@ -210,20 +146,10 @@ function iconSetXml(rule) {
     const anchors = (rule.cfvo ?? []).map(cfvoXml).join('');
     return `<iconSet${name}>${anchors}</iconSet>`;
 }
-// One scale anchor. `min`/`max` carry no value; the rest state theirs in `val` (a formula anchor's
-// value is its formula text, escaped like any attribute).
 function cfvoXml(cfvo) {
     const val = cfvo.value !== undefined ? ` val="${escapeAttr(String(cfvo.value))}"` : '';
     return `<cfvo type="${escapeAttr(cfvo.type)}"${val}/>`;
 }
-/**
- * Parse a worksheet's conditional formatting into the model. The classic `<conditionalFormatting>`
- * blocks supply every rule; the x14 extension (`<x14:conditionalFormatting>` inside `<extLst>`) is
- * read only to enrich a classic data bar with the facets the classic element cannot carry — the
- * gradient flag and the negative-fill and axis colours — matched by the shared id the two ends link
- * on. An extension rule with no classic counterpart (a rule that lives only in x14) is ignored, so it
- * is never half-read into a broken classic rule.
- */
 export function parseConditionalFormattings(xml) {
     const blocks = [];
     let block;
@@ -231,9 +157,6 @@ export function parseConditionalFormattings(xml) {
     let scale;
     let capturingFormula = false;
     let formulaText = '';
-    // Classic data-bar rules that named an extension, paired with the id they linked on, plus the
-    // extensions gathered from the worksheet <extLst>. The two are married after the pass — the
-    // extension always follows the classic blocks in document order, so it is known by then.
     const linked = [];
     const extById = new Map();
     let x14Ext;
@@ -244,8 +167,6 @@ export function parseConditionalFormattings(xml) {
         onOpen(name, attrs, selfClosing) {
             const ln = localName(name);
             if (name.includes(':')) {
-                // The `<x14:id>` a classic data bar carries to name its extension: capture its text into the
-                // open draft. The rest are the worksheet extension's own elements.
                 if (ln === 'id' && draft !== undefined) {
                     capturingX14Id = true;
                     x14IdText = '';
@@ -255,7 +176,6 @@ export function parseConditionalFormattings(xml) {
                     x14ExtId = attrs.id;
                 }
                 else if (x14Ext !== undefined && ln === 'dataBar') {
-                    // gradient defaults to true in the x14 schema, so an absent attribute reads as a gradient.
                     x14Ext.gradient = attrs.gradient !== '0';
                 }
                 else if (x14Ext !== undefined && ln === 'negativeFillColor') {
@@ -270,8 +190,6 @@ export function parseConditionalFormattings(xml) {
                 block = { ref: attrs.sqref ?? '', rules: [] };
             }
             else if (ln === 'cfRule' && block !== undefined) {
-                // A rule with no operands (e.g. duplicateValues) is a self-closing element that fires no
-                // close event, so it must be finalised here; one with children waits for its </cfRule>.
                 if (selfClosing) {
                     block.rules.push(finalizeRule(newDraft(attrs)));
                 }
@@ -360,12 +278,6 @@ export function parseConditionalFormattings(xml) {
 function emptyExt() {
     return { gradient: undefined, negativeFillColor: undefined, axisColor: undefined };
 }
-/**
- * Extract the differential-style (`<dxf>`) fragments from styles.xml, each verbatim. Preserving the
- * raw XML — rather than reparsing and re-serialising — is what keeps a foreign dxf's number format a
- * real format code on re-write instead of a coerced `"[object Object]"`, and keeps every conditional
- * formatting's `dxfId` index pointing at the same style it did in the source file.
- */
 export function parseDxfs(stylesXml) {
     const block = /<dxfs\b[^>]*>([\s\S]*?)<\/dxfs>/.exec(stylesXml);
     if (block === null)
@@ -385,7 +297,6 @@ function newDraft(attrs) {
         stdDev: parseFiniteAttr(attrs.stdDev),
         percent: boolStrict(attrs.percent),
         bottom: boolStrict(attrs.bottom),
-        // aboveAverage defaults to true in OOXML; only an explicit "0" means below-average.
         aboveAverage: attrs.aboveAverage === undefined ? undefined : attrs.aboveAverage !== '0',
         equalAverage: boolStrict(attrs.equalAverage),
         dxfId: parseIndexAttr(attrs.dxfId),
@@ -397,18 +308,12 @@ function newDraft(attrs) {
         x14Id: undefined,
     };
 }
-// priority/rank/stdDev must be finite; a malformed value is dropped rather than propagated as NaN —
-// `priority` in particular feeds the writer's running priority counter (see `ruleXml`), so one bad
-// value would otherwise poison every later rule's auto-assigned priority on the same sheet.
 function parseFiniteAttr(value) {
     if (value === undefined)
         return undefined;
     const n = Number(value);
     return Number.isFinite(n) ? n : undefined;
 }
-// dxfId is preserved as the raw string (not renumbered) so it keeps pointing at the same slot in the
-// dxf table on re-write; it must still be a non-negative integer, so a malformed value is dropped
-// rather than later coercing to `dxfId="NaN"` in {@link resolveDxfId}.
 function parseIndexAttr(value) {
     if (value === undefined)
         return undefined;
@@ -457,7 +362,6 @@ function parseCfvo(attrs) {
     const type = (attrs.type ?? 'num');
     const cfvo = { type };
     if (attrs.val !== undefined) {
-        // A `formula` anchor's value is an expression and stays a string; the rest are numeric.
         cfvo.value = type === 'formula' ? attrs.val : coerceNumericLiteral(attrs.val);
     }
     return cfvo;

package/dist/io/xlsx/data-validation.js

@@ -1,30 +1,8 @@
-// Data validation I/O — the sheet-level `<dataValidations>` element and the reader that folds each
-// rule back onto its range.
-//
-// A validation stores its operands in `<formula1>`/`<formula2>` child elements and its target in a
-// `sqref` attribute. The operand text carries NO leading '=' (the '=' is an authoring convention, not
-// part of the stored formula), so the writer strips one and the reader keeps whatever it finds. A
-// numeric-typed rule's literal operand parses to a number; a cell reference, defined name, or list
-// source keeps its string, so a reference is never coerced to NaN and lost.
-//
-// The extended `<x14:dataValidation>` form (2009 extension schema) carries the validations a legacy
-// element cannot express — chiefly a list whose source lives on another sheet. It lives in the
-// worksheet `<extLst>`, keeps its target in a `<xm:sqref>` child rather than a `sqref` attribute, and
-// wraps each operand in an `<xm:f>` under `<x14:formula1>`/`<x14:formula2>`. A rule read from that
-// form is tagged `extended` so it is written back there; the two forms are parsed and serialised by
-// prefix so neither reader mistakes one for the other.
 import { escapeAttr, escapeText, stripFormulaEquals } from '../../xml/xml.js';
 import { boolStrict, coerceNumericLiteral, localName, parseXml } from '../../xml/xml-read.js';
-// The x14/xm extension namespaces and `DATA_VALIDATION_EXT_URI` are declared inline on the elements
-// that need them, exactly as Excel writes them, so the block is self-contained and the worksheet root
-// needs no extra namespace declaration.
 import { DATA_VALIDATION_EXT_URI, XM_NS } from './namespaces.js';
 import { x14Ext } from './x14-ext.js';
-// The typed validations whose literal operands are numbers; `list`/`custom` operands stay strings.
 const TYPED = new Set(['whole', 'decimal', 'date', 'time', 'textLength']);
-/** The standard `<dataValidations>` element for the rules stored in the legacy form, or '' when the
- * sheet has none of them — so a sheet with only extended (or no) validations stays byte-clean here.
- * The extended rules are emitted separately by {@link dataValidationsExtXml}. */
 export function dataValidationsXml(entries) {
     const standard = entries.filter((entry) => !entry.extended);
     if (standard.length === 0)
@@ -32,9 +10,6 @@ export function dataValidationsXml(entries) {
     const items = standard.map(({ sqref, rule }) => dataValidationXml(sqref, rule)).join('');
     return `<dataValidations count="${standard.length}">${items}</dataValidations>`;
 }
-/** The `<ext>` carrying the extended (`<x14:dataValidation>`) rules, or '' when the sheet declares
- * none. Emitted bare (no `<extLst>` wrapper) so the worksheet serialiser can gather it into a single
- * `<extLst>` beside the conditional-formatting extension — a worksheet may carry at most one. */
 export function dataValidationsExtXml(entries) {
     const extended = entries.filter((entry) => entry.extended);
     if (extended.length === 0)
@@ -42,10 +17,6 @@ export function dataValidationsExtXml(entries) {
     const items = extended.map(({ sqref, rule }) => extendedDataValidationXml(sqref, rule)).join('');
     return x14Ext(DATA_VALIDATION_EXT_URI, `<x14:dataValidations count="${extended.length}" xmlns:xm="${XM_NS}">${items}</x14:dataValidations>`);
 }
-// The shared attributes of a validation, in CT_DataValidation order: type, errorStyle, operator,
-// allowBlank, showInputMessage, showErrorMessage, errorTitle, error, promptTitle, prompt. The target
-// range differs between the two forms (a `sqref` attribute vs an `<xm:sqref>` child), so it is not
-// part of this shared prefix.
 function ruleAttrs(rule) {
     return (` type="${rule.type}"` +
         (rule.errorStyle !== undefined ? ` errorStyle="${rule.errorStyle}"` : '') +
@@ -58,25 +29,17 @@ function ruleAttrs(rule) {
         (rule.promptTitle !== undefined ? ` promptTitle="${escapeAttr(rule.promptTitle)}"` : '') +
         (rule.prompt !== undefined ? ` prompt="${escapeAttr(rule.prompt)}"` : ''));
 }
-// The standard element: shared attributes, then `sqref` last, then `<formula1>`/`<formula2>` bodies.
 function dataValidationXml(sqref, rule) {
     const [f1, f2] = operands(rule);
     const body = (f1 !== undefined ? `<formula1>${escapeText(stripFormulaEquals(f1))}</formula1>` : '') +
         (f2 !== undefined ? `<formula2>${escapeText(stripFormulaEquals(f2))}</formula2>` : '');
     return `<dataValidation${ruleAttrs(rule)} sqref="${escapeAttr(sqref)}">${body}</dataValidation>`;
 }
-// A rule's two operands with any non-finite numeric bound dropped: a NaN/±Infinity operand (e.g. a
-// date validation whose bound failed to coerce to a serial) has no OOXML representation, so it is
-// omitted rather than serialised as the literal "NaN" — the same graceful degradation a non-finite
-// cell value gets.
 function operands(rule) {
     const drop = (v) => typeof v === 'number' && !Number.isFinite(v) ? undefined : v;
     const [f1, f2] = rule.formulae ?? [];
     return [drop(f1), drop(f2)];
 }
-// The extended element: same shared attributes, but each operand wraps in `<x14:formula1><xm:f>…` and
-// the target range is an `<xm:sqref>` child that follows the formulae. The `xr:uid` Excel adds is
-// revision metadata it regenerates freely, so it is not modelled or re-emitted.
 function extendedDataValidationXml(sqref, rule) {
     const [f1, f2] = operands(rule);
     const body = (f1 !== undefined
@@ -88,7 +51,6 @@ function extendedDataValidationXml(sqref, rule) {
         `<xm:sqref>${escapeText(sqref)}</xm:sqref>`;
     return `<x14:dataValidation${ruleAttrs(rule)}>${body}</x14:dataValidation>`;
 }
-/** Parse every standard `<dataValidation>` out of a worksheet part into range-bound rules. */
 export function parseDataValidations(xml) {
     const entries = [];
     let current;
@@ -96,7 +58,6 @@ export function parseDataValidations(xml) {
     parseXml(xml, {
         onOpen(name, attrs) {
             const ln = localName(name);
-            // Only the standard, unprefixed element — an `x14:dataValidation` is left for the extended path.
             if (ln === 'dataValidation' && !name.includes(':')) {
                 current = { attrs, formulae: [] };
             }
@@ -137,9 +98,6 @@ function buildEntry(attrs, formulae) {
     const rule = buildRule(attrs, formulae);
     return rule === undefined ? undefined : { sqref, rule };
 }
-// The rule carried by a validation element of either form: its attributes decide the type, operator,
-// flags, and messages; its `<formula1>`/`<formula2>` operands become `formulae`. The target range is
-// supplied separately by each form's caller, so it is not read here.
 function buildRule(attrs, formulae) {
     const { type } = attrs;
     if (type === undefined)
@@ -149,8 +107,6 @@ function buildRule(attrs, formulae) {
         rule.operator = attrs.operator;
     }
     else if (TYPED.has(type)) {
-        // Excel omits `operator="between"` because it is the default for a typed rule; restore it so a
-        // reader sees the operator the rule actually enforces.
         rule.operator = 'between';
     }
     if (boolStrict(attrs.allowBlank))
@@ -169,9 +125,6 @@ function buildRule(attrs, formulae) {
         rule.prompt = attrs.prompt;
     if (attrs.promptTitle !== undefined)
         rule.promptTitle = attrs.promptTitle;
-    // A `list`/`custom` operand is always a string (a source list or an expression); every other
-    // type's literal operand coerces to a number when it is one, so a numeric bound reads back as a
-    // number while a cell reference or defined name survives as its verbatim string.
     const parsed = formulae
         .filter((f) => f !== undefined)
         .map((f) => (type === 'list' || type === 'custom' ? f : coerceNumericLiteral(f)));
@@ -179,15 +132,9 @@ function buildRule(attrs, formulae) {
         rule.formulae = parsed;
     return rule;
 }
-/** Parse every extended `<x14:dataValidation>` out of a worksheet's `<extLst>` into range-bound
- * rules tagged `extended`, so a cross-sheet or whole-column list validation Excel stored only in the
- * 2009 extension form is read back rather than dropped. The standard parser ignores these (they are
- * prefixed); this one, symmetrically, handles only the prefixed elements. */
 export function parseExtendedDataValidations(xml) {
     const entries = [];
     let current;
-    // Which operand an `<xm:f>` feeds (set by the enclosing `<x14:formula1>`/`<x14:formula2>`), and
-    // which child element's text is currently being gathered.
     let slot;
     let capture;
     let text = '';
@@ -195,7 +142,6 @@ export function parseExtendedDataValidations(xml) {
         onOpen(name, attrs) {
             const ln = localName(name);
             const prefixed = name.includes(':');
-            // A `<x14:dataValidation>`; its attributes (type, flags, messages) build the rule.
             if (ln === 'dataValidation' && prefixed) {
                 current = { attrs, formulae: [], sqref: '' };
             }
@@ -249,8 +195,6 @@ function buildExtendedEntry(attrs, formulae, sqref) {
     const rule = buildRule(attrs, formulae);
     return rule === undefined ? undefined : { sqref, rule, extended: true };
 }
-/** Fold parsed validations onto a sheet, each bound to its original range and carrying its form: an
- * `extended` entry is re-attached as extended so a round-trip writes it back to the x14 block. */
 export function applyDataValidations(sheet, entries) {
     for (const { sqref, rule, extended } of entries) {
         sheet.addDataValidation(sqref, rule, extended ? { extended: true } : {});