@shbernal/ts-xlsx 1.1.0 → 1.2.0

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 } : {});

package/dist/io/xlsx/edit-vba.js

@@ -1,18 +1,3 @@
-// Structurally edit an existing `.xlsm` at the *package* level: remove a module, or add a reference,
-// returning new package bytes with every other part preserved byte-for-byte. Only `xl/vbaProject.bin` is
-// rewritten (plus dropping a now-stale signature); worksheets, styles, drawings, and every other part
-// ride through untouched.
-//
-// This is the highest-fidelity way to tweak an existing macro project. The alternative — `readXlsx` →
-// the matching `Workbook` method → `writeXlsx` — rebuilds the whole package from the parsed model, which
-// re-serialises every part and so only preserves what the model captures. For a rich, real-world
-// workbook that round-trip can perturb parts Excel is strict about; splicing the original bytes cannot,
-// because it never re-authors anything but the macro project. Use this when the input is a real file
-// whose non-macro content must be preserved exactly.
-//
-// Authoring or editing module SOURCE is not here: Excel runs a module's compiled p-code, not its source,
-// so that needs the offline `tools/vba-compiler` (VBIDE), which can produce a whole edited `.xlsm`
-// directly (ADR 0019).
 import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
 import { VbaAuthorError } from '../../vba/errors.js';
 import { addVbaReference, removeVbaModule, } from '../../vba/project-editor.js';
@@ -20,42 +5,14 @@ import { relsPathFor } from '../opc/part-paths.js';
 import { parseRelationshipRecords, relationshipTargetByType, resolveRelativePart, resolveWorkbookPart, } from '../opc/read-opc.js';
 const OFFICE_DOCUMENT_REL = 'officeDocument';
 const VBA_PROJECT_REL = 'vbaProject';
-// Every signature flavour Excel writes over a VBA project (legacy, agile, V3) shares this local-name
-// prefix; all become stale the instant the project's bytes change and must be dropped with it.
 const VBA_SIGNATURE_REL_INFIX = 'vbaProjectSignature';
-/**
- * Remove a standard module from an existing macro-enabled package's VBA project, returning new package
- * bytes. Every part but `xl/vbaProject.bin` is preserved byte-for-byte (see {@link removeVbaModule} for
- * what changes within it), and any digital signature over the old project is dropped because it cannot
- * validate the new bytes.
- *
- * @throws {VbaAuthorError} if the package carries no VBA project, `name` is not in the project, or names
- *   a `document`/`designer` module.
- * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
- */
 export function editXlsxVbaRemoveModule(xlsx, name) {
     return applyToVbaProjectPart(xlsx, (bin) => removeVbaModule(bin, name));
 }
-/**
- * Add a registered (COM type-library) reference to an existing macro-enabled package's VBA project,
- * returning new package bytes. Every part but `xl/vbaProject.bin` is preserved byte-for-byte (see
- * {@link addVbaReference} for what changes within it), and any digital signature over the old project is
- * dropped because it cannot validate the new bytes.
- *
- * @throws {VbaAuthorError} if the package carries no VBA project, or any field of `ref` is invalid (see
- *   {@link VbaLibraryReference}).
- * @throws {VbaParseError} if the attached `vbaProject.bin` is malformed.
- */
 export function editXlsxVbaAddReference(xlsx, ref) {
     return applyToVbaProjectPart(xlsx, (bin) => addVbaReference(bin, ref));
 }
-// Shared plumbing for every package-level VBA edit: unzip, locate `xl/vbaProject.bin`, replace it with
-// whatever `apply` produces, drop a now-stale signature, and re-zip. `apply` is expected to validate
-// fail-closed itself (every project-editor primitive does), so a bad edit throws before `files` is
-// touched.
 function applyToVbaProjectPart(xlsx, apply) {
-    // Widen off fflate's `Uint8Array<ArrayBuffer>` element type so spliced/re-serialised parts (whose
-    // buffers are `ArrayBufferLike`) assign back into the map.
     const files = unzipSync(xlsx);
     const binPath = locateVbaProjectPart(files);
     const bin = binPath === undefined ? undefined : files[binPath];
@@ -66,9 +23,6 @@ function applyToVbaProjectPart(xlsx, apply) {
     dropStaleSignature(files, binPath);
     return zipSync(files);
 }
-// Resolve the package's `xl/vbaProject.bin` part the way the reader does: `_rels/.rels` → the
-// officeDocument (workbook) part → its `.rels` → the `vbaProject` relationship, each target resolved
-// relative to its referrer. undefined when the package declares no such relationship (a macro-free book).
 function locateVbaProjectPart(files) {
     const rootRels = textPart(files, '_rels/.rels');
     if (rootRels === undefined)
@@ -85,8 +39,6 @@ function locateVbaProjectPart(files) {
         return undefined;
     return resolveVbaTarget(workbookPath, vbaTarget);
 }
-// The workbook's vbaProject relationship uses a workbook-relative target (`vbaProject.bin`); resolve it
-// through the workbook-part rule so both that and an absolute `/xl/vbaProject.bin` land on the part path.
 function resolveVbaTarget(workbookPath, target) {
     if (target.startsWith('/'))
         return target.slice(1);
@@ -94,9 +46,6 @@ function resolveVbaTarget(workbookPath, target) {
         return resolveWorkbookPart(target);
     return resolveRelativePart(workbookPath, target);
 }
-// Editing the project invalidates any signature over it, so remove every signature part the project's
-// `.rels` reaches, the relationships that point at them, and their content-type overrides — leaving a
-// package that advertises no signature rather than a broken one (mirrors Workbook.vbaProjectBytes).
 function dropStaleSignature(files, binPath) {
     const binRelsPath = relsPathFor(binPath);
     const binRels = textPart(files, binRelsPath);
@@ -125,12 +74,9 @@ function textPart(files, path) {
     const bytes = files[path];
     return bytes === undefined ? undefined : strFromU8(bytes);
 }
-// Drop the `<Relationship>` element carrying a given Id, matching the element as a whole (self-closing
-// or paired) so attribute order does not matter.
 function removeRelationshipById(xml, id) {
     return xml.replace(/<Relationship\b[^>]*?\/>|<Relationship\b[\s\S]*?<\/Relationship>/g, (element) => (new RegExp(`\\bId="${escapeRegExp(id)}"`).test(element) ? '' : element));
 }
-// Drop the `<Override>` naming a given part path; PartName is the full, unambiguous package path.
 function removeContentTypeOverride(xml, partPath) {
     return xml.replace(/<Override\b[^>]*?\/>/g, (element) => element.includes(`PartName="/${partPath}"`) ? '' : element);
 }

package/dist/io/xlsx/errors.js

@@ -1,16 +1,4 @@
 import { XlsxError } from '../../errors.js';
-/**
- * Thrown when an `.xlsx` package's XML content is well-formed but does not describe a workbook this
- * library can act on — a `xl/workbook.xml` that declares no worksheets, say.
- *
- * It sits between two neighbours. {@link XmlParseError} reports that the *markup* did not parse;
- * {@link UnsupportedFormatError} reports that the *container* is not one we read at all. This one
- * fires when both of those were fine and the document itself is nonetheless not a workbook.
- *
- * The reader is deliberately lenient about content it does not recognise — an unknown element is
- * skipped, not fatal — so this is rare by design, and reaching it means something a workbook cannot
- * do without being corrupt.
- */
 export class XlsxParseError extends XlsxError {
     name = 'XlsxParseError';
     code = 'malformed-input';

package/dist/io/xlsx/hyperlinks.js

@@ -1,28 +1,13 @@
-// Cell hyperlinks — the sheet-level `<hyperlinks>` element, its external relationships, and the
-// reader that folds a link back onto its cell's value.
-//
-// A hyperlink is not stored inside the cell in OOXML: the `<c>` holds only the visible label (a
-// normal string value), while a separate `<hyperlink>` child of `<worksheet>` ties an A1 reference
-// to a destination. An EXTERNAL destination (a URL) is reached indirectly, through a sheet
-// relationship carrying `TargetMode="External"` that the `<hyperlink>` names by `r:id`. An INTERNAL
-// destination (a location inside the same workbook, which the author writes as a `#`-prefixed value)
-// is held directly in a `location` attribute with NO relationship — emitting an internal target as an
-// external relationship makes a strict consumer resolve both the rel and the location and render the
-// destination doubled.
 import { decodeRange } from '../../core/address.js';
 import { isHyperlinkValue, isRichTextValue } from '../../core/value.js';
 import { escapeAttr } from '../../xml/xml.js';
 import { localName, parseXml } from '../../xml/xml-read.js';
-/** Gather every hyperlink cell on a sheet, in row-major order. */
 export function collectHyperlinks(sheet) {
     const links = [];
     for (const { cells } of sheet.rows()) {
         for (const cell of cells) {
             const value = cell.value;
             if (isHyperlinkValue(value)) {
-                // A link that spans a range carries its extent in `range`; the anchor cell (this one) is the
-                // range's top-left. Emit that extent as `ref` so the clickable area survives, falling back to
-                // the single cell for an ordinary link.
                 links.push({
                     ref: value.range ?? cell.address,
                     target: value.hyperlink,
@@ -33,22 +18,15 @@ export function collectHyperlinks(sheet) {
     }
     return links;
 }
-/** Split collected links into internal (location, no rel) and external (relationship) forms, drawing
- * each external link's relationship id from the sheet's allocator so external ids follow every other
- * sheet-local relationship in canonical order. An internal ('#'-prefixed) link consumes no id. */
 export function planHyperlinks(links, rels) {
     return links.map((link) => {
         const tooltip = link.tooltip !== undefined ? { tooltip: link.tooltip } : {};
-        // A '#'-prefixed target is an internal document location: held verbatim in `location`, with no
-        // relationship. Everything else is an external URL reached through a relationship.
         if (link.target.startsWith('#')) {
             return { ref: link.ref, location: link.target.slice(1), ...tooltip };
         }
         return { ref: link.ref, relId: rels.next(), target: link.target, ...tooltip };
     });
 }
-/** The `<hyperlinks>` element, or '' when the sheet has none. Attribute order follows CT_Hyperlink:
- * `ref`, `r:id`, `location`, `tooltip`. */
 export function hyperlinksXml(links) {
     if (links.length === 0)
         return '';
@@ -62,7 +40,6 @@ export function hyperlinksXml(links) {
         .join('');
     return `<hyperlinks>${items}</hyperlinks>`;
 }
-/** Parse every `<hyperlink>` element out of a worksheet part. */
 export function parseSheetHyperlinks(xml) {
     const links = [];
     parseXml(xml, {
@@ -82,26 +59,17 @@ export function parseSheetHyperlinks(xml) {
     });
     return links;
 }
-/** Fold parsed hyperlinks onto a sheet's cells, wrapping each cell's existing value (its visible
- * label) into a {@link HyperlinkValue}. `rels` maps a relationship id to its target URL. */
 export function applyHyperlinks(sheet, links, rels) {
     for (const link of links) {
         const target = resolveTarget(link, rels);
         if (target === undefined)
             continue;
-        // A hyperlink may span a range (`ref="D1:H1"`); Excel anchors the link at the range's top-left
-        // cell. Decode once so a multi-cell link folds onto that anchor rather than asking the sheet for
-        // a range address it cannot resolve. A ref that does not decode is skipped, not fatal.
         const decoded = decodeRefSafe(link.ref);
         if (decoded === undefined)
             continue;
         const cell = sheet.getCell(decoded.tl.address);
-        // The visible label is the cell's own value: a plain string, or rich text when the label
-        // carried per-run formatting. Any other value kind has no textual label, so it reads as empty.
         const cellValue = cell.value;
         const text = typeof cellValue === 'string' ? cellValue : isRichTextValue(cellValue) ? cellValue : '';
-        // Record the extent only when the link genuinely spans more than the anchor, so an ordinary
-        // single-cell link stays a plain value and the range survives verbatim for a multi-cell one.
         const spansRange = decoded.tl.address !== decoded.br.address;
         const value = {
             hyperlink: target,
@@ -112,10 +80,6 @@ export function applyHyperlinks(sheet, links, rels) {
         cell.value = value;
     }
 }
-// A hyperlink's `ref` decoded to a range (a single-cell ref decodes to a range whose corners
-// coincide), so the caller can both anchor on the top-left and tell whether the link spans further.
-// Returns undefined for a ref that does not decode, so a malformed hyperlink is dropped rather than
-// crashing the load.
 function decodeRefSafe(ref) {
     try {
         return decodeRange(ref);
@@ -129,11 +93,7 @@ function resolveTarget(link, rels) {
         const base = rels.get(link.rid);
         if (base === undefined)
             return undefined;
-        // A foreign file may split an external URL's fragment into the `location` attribute, apart from
-        // the relationship Target; rejoin them so the whole URL survives. Our own writer keeps the
-        // fragment in the Target, so a link we wrote never carries both.
         return link.location !== undefined ? `${base}#${link.location}` : base;
     }
-    // No relationship: an internal ('#'-prefixed) target held verbatim in `location`.
     return link.location !== undefined ? `#${link.location}` : undefined;
 }