@shbernal/ts-xlsx 1.1.0 → 1.2.0

package/dist/core/comment-thread.js

@@ -1,30 +1,4 @@
-// Modern threaded comments in the model — the review-style conversations Excel has written since 2018:
-// an anchored discussion of authored messages with timestamps, replies, a resolved state, and
-// @mentions. Distinct from a legacy note (`cell.note`), which is a single anonymous annotation; Excel's
-// own UI draws the same line, calling these "comments" and those "notes". A cell carries one or the
-// other, never both.
-//
-// The wire form lives in two parts (see `io/xlsx/threaded-comments.ts`): the messages per sheet, and a
-// workbook-level identity registry the messages point into. The model mirrors that split — a thread's
-// authors and mentioned people are {@link Person} entries resolved through
-// {@link Workbook.getPerson}, not names duplicated onto every message.
-// A GUID in any of the spellings a caller plausibly has one in — braced or bare, upper or lower case.
-// `crypto.randomUUID()` produces the bare lower-case form, so accepting only the canonical spelling would
-// reject the one obvious way to make an id in JavaScript.
 const GUID = /^\{?([0-9a-f]{8})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{4})-([0-9a-f]{12})\}?$/i;
-/**
- * The one spelling every threaded-comment identifier must take on the wire: brace-wrapped, upper-case hex.
- *
- * Verified against the OOXML schema, which pins `person/@id`, a message's `id`/`personId`/`parentId`, and a
- * mention's `mentionpersonId`/`mentionId` to exactly `\{[0-9A-F]{8}-…\}` — a bare GUID and a lower-case one
- * are each rejected outright. So this normalises rather than merely checking: a caller passing
- * `crypto.randomUUID()` gets a valid file instead of one Excel offers to repair.
- *
- * The authoring path alone goes through here. A file's own ids are re-emitted as the file wrote them, since
- * a reader that rewrote them would break every reference pointing at them.
- *
- * @throws {SyntaxError} if the value is not a GUID in any spelling.
- */
 export function commentThreadGuid(value, what) {
     const match = GUID.exec(value.trim());
     if (match === null) {
@@ -33,26 +7,7 @@ export function commentThreadGuid(value, what) {
     }
     return `{${match.slice(1).join('-').toUpperCase()}}`;
 }
-/**
- * The largest value a mention offset can take on the wire. Verified against the OOXML schema: both
- * `startIndex` and `length` are `xsd:unsignedInt`, so `4294967295` validates and `4294967296` is rejected
- * as "not a valid 'UInt32' value".
- *
- * Wildly beyond any real message, and that is the point — the ceiling exists so a value from a hostile
- * part can never reach the serialiser. JavaScript spells a large enough number in exponent form
- * (`String(1e21)` is `"1e+21"`), which is not a numeric literal any schema accepts, and one invalid
- * attribute is enough for Excel to offer to repair the whole conversation away.
- */
 export const MENTION_OFFSET_MAX = 0xffff_ffff;
-/**
- * A mention offset as the wire accepts it: a whole number within {@link MENTION_OFFSET_MAX}.
- *
- * The authoring path alone throws. A file's own mentions are read leniently — one carrying an unusable
- * offset is dropped, keeping the message text and losing only the chip — because a foreign generator's
- * arithmetic is not something a caller can fix, whereas their own is.
- *
- * @throws {SyntaxError} if the value is negative, fractional, or beyond the wire's ceiling.
- */
 export function commentThreadOffset(value, what) {
     if (!Number.isInteger(value) || value < 0 || value > MENTION_OFFSET_MAX) {
         throw new SyntaxError(`${what} must be a whole number between 0 and ${MENTION_OFFSET_MAX} — a mention's span is ` +

package/dist/core/conditional-formatting-overlay.js

@@ -1,23 +1,12 @@
-// The conditional-formatting overlay a Worksheet owns: an insertion-ordered, defensively-copied list
-// of range-bound rule sets. Kept as its own class, the sibling to {@link DataValidationOverlay}, so
-// Worksheet delegates the collection's storage and cloning rather than managing the array itself.
 import { cloneConditionalFormatting } from './conditional-formatting.js';
 export class ConditionalFormattingOverlay {
     #entries = [];
-    /**
-     * Attach a conditional formatting to a target range. `formatting.ref` is an OOXML `sqref` — one
-     * range (`"A1:A10"`), a whole column, or several space-separated areas (`"A1:C1 A3:C3"`) sharing one
-     * rule set. The block is stored once against the range, defensively copied so the getter never hands
-     * back a reference into the caller's object.
-     */
     add(formatting) {
         this.#entries.push(cloneConditionalFormatting(formatting));
     }
-    /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
     get entries() {
         return this.#entries;
     }
-    /** Drop every conditional formatting, leaving the overlay empty. */
     clear() {
         this.#entries.length = 0;
     }

package/dist/core/conditional-formatting.js

@@ -1,13 +1,3 @@
-// Conditional formatting — the rules that restyle a cell based on its value (a data bar, a colour
-// scale, a "highlight cells greater than 10", a formula-driven expression). Like a data validation,
-// it is a worksheet-level overlay keyed by a target range, not a facet owned by one cell: one rule
-// covers a whole range, and several rules can layer on the same cells with an evaluation precedence.
-//
-// The model carries the operands each rule type needs and otherwise leaves them absent. A rule type
-// the library does not interpret in depth still round-trips its `type`, `priority`, `operator`,
-// `formulae`, and differential-style reference — so a read/write cycle never silently drops a rule.
-/** A defensive deep copy, so a stored conditional formatting never aliases the caller's object nor
- * any of its nested arrays (rules, formulae, cfvo, colours) or the differential style. */
 export function cloneConditionalFormatting(cf) {
     return { ref: cf.ref, rules: cf.rules.map(cloneRule) };
 }

package/dist/core/containers.js

@@ -1,23 +1,8 @@
-// Identity-preserving replacement of a container's contents.
-//
-// Several model fields are `readonly` fields holding a mutable object or array: a caller (or a live
-// getter) may hold a durable reference to the container, so importing a model must replace what the
-// container *holds* without swapping the container itself. These two primitives do that — one for an
-// object's keys, one for an array's elements — so the field's identity survives a wholesale reload.
-// Replace an object's contents in place: clear every own key, then copy `source`'s keys over. Used for
-// fields like a worksheet's `properties`/`pageSetup`/`headerFooter`, which are `readonly` fields holding
-// mutable objects, so importing a model must overwrite them rather than reassign — and clear any stale
-// key the incoming model does not carry. `Reflect` deletes each existing key without pretending the
-// object carries a string index signature.
 export function overwrite(target, source) {
     for (const key of Reflect.ownKeys(target))
         Reflect.deleteProperty(target, key);
     Object.assign(target, source);
 }
-// Replace an array's contents in place: clear it, then append `next` element by element. Appends
-// individually rather than spreading `next` into a single `push(...next)` call, whose argument count the
-// JS engine bounds by its call-stack limit — these arrays are filled from parsed files, so a hostile
-// input must not be able to overflow that limit.
 export function replaceContents(array, next) {
     array.length = 0;
     for (const item of next)

package/dist/core/data-validation-overlay.js

@@ -1,27 +1,9 @@
-// The data-validation overlay a Worksheet owns: an insertion-ordered list of range-bound rules, plus
-// the decoded rectangles a point-in-rect lookup ({@link DataValidationOverlay.at}) tests against. Kept
-// as its own class — the sibling to {@link GridEdits} that owns splice arithmetic — rather than inline
-// on Worksheet, since a validation's storage (a rule plus its decoded ranges) is a self-contained unit
-// Worksheet only ever adds to, reads, or clears wholesale.
 import { cloneDataValidation, } from './data-validation.js';
 import { decodeSqrefRects } from './merge.js';
 export class DataValidationOverlay {
     #entries = [];
     #rects = [];
-    /**
-     * Attach a rule to a target range (`"B2:B20"`, a whole column `"B2:B1048576"`, or a space-separated
-     * `sqref` of several ranges). The rule is stored once against the range, not copied per covered
-     * cell, so a whole-column dropdown stays a single entry. A cell inside the range reports the rule
-     * through {@link at}.
-     *
-     * Pass `{extended: true}` to mark a rule that belongs in the 2009 extension form
-     * (`<x14:dataValidation>`) — the carrier Excel uses for a list source on another sheet and other
-     * shapes the standard element cannot express. The reader sets it for a rule found in that form so a
-     * round-trip writes it back there instead of silently corrupting the cross-sheet reference.
-     */
     add(sqref, rule, options = {}) {
-        // One defensive copy, shared by the serialisable entry and the lookup index, so the getter never
-        // hands back a reference into the caller's object.
         const stored = cloneDataValidation(rule);
         const entry = { sqref, rule: stored };
         if (options.extended)
@@ -29,15 +11,9 @@ export class DataValidationOverlay {
         this.#entries.push(entry);
         this.#rects.push({ rects: decodeSqrefRects(sqref), rule: stored });
     }
-    /** The data validations on this sheet, each bound to its target range, in insertion order. */
     get entries() {
         return this.#entries;
     }
-    /**
-     * The validation covering the 1-based `col`/`row`, or `undefined` when none does. The first added
-     * rule whose range contains the cell wins, mirroring how a spreadsheet resolves overlapping
-     * validations.
-     */
     at(col, row) {
         for (const { rects, rule } of this.#rects) {
             for (const rect of rects) {
@@ -48,7 +24,6 @@ export class DataValidationOverlay {
         }
         return undefined;
     }
-    /** Drop every validation, leaving the overlay empty. */
     clear() {
         this.#entries.length = 0;
         this.#rects.length = 0;

package/dist/core/data-validation.js

@@ -1,10 +1,3 @@
-// Data validation — the input constraints Excel enforces on a cell (a dropdown list, a numeric
-// range, a length limit, a custom formula). Unlike a style facet, a validation is not owned by one
-// cell: it is a worksheet-level overlay keyed by a target range (`sqref`), and a cell inherits
-// whichever rule's range contains it. Keying by range is what keeps a whole-column dropdown a single
-// entry rather than a million per-cell copies.
-/** A defensive copy of a rule, so a stored validation never aliases the caller's object (nor its
- * `formulae` array). */
 export function cloneDataValidation(rule) {
     return {
         ...rule,

package/dist/core/date.js

@@ -1,54 +1,15 @@
-// Excel date serials — the bridge between a JS `Date` and OOXML's numeric storage.
-//
-// A spreadsheet never stores a date as such: it stores a number (the "serial") and a
-// number format that tells the viewer to render that number as a date. Serial 1 is
-// 1900-01-01. The catch is a bug Excel has carried since 1985 and every consumer must
-// reproduce for compatibility: the 1900 date system counts a phantom 1900-02-29 that
-// never existed (serial 60), so serials at or below 59 sit one calendar day later than
-// a naive "days since the epoch" offset would place them. Round-tripping a date means
-// reproducing that quirk faithfully in both directions, or imported pre-March-1900
-// dates land a day early.
-//
-// Dates here are treated as UTC wall-clock: a serial carries no timezone, so we convert
-// against a UTC epoch in both directions. A `Date` written and read back through this
-// module is exact; the caller owns any timezone interpretation before it reaches here.
 const MS_PER_DAY = 86_400_000;
-// Serial 0 in the 1900 date system is nominally 1899-12-30. The phantom leap day lives
-// at serial 60, so the offset correction pivots there.
 const EPOCH_1900_UTC = Date.UTC(1899, 11, 30);
 const PHANTOM_SERIAL = 60;
-/**
- * The number format applied to a `Date` cell that carries no explicit format of its own,
- * so the value renders — and reads back — as a date rather than a bare serial number.
- */
 export const DEFAULT_DATE_NUMFMT = 'yyyy-mm-dd';
-/**
- * Convert a JS `Date` to its 1900-system Excel serial, reproducing the phantom-leap-day
- * quirk so the value renders on the calendar date Excel would show. Fractional serials
- * carry the time of day. The caller must reject a non-finite (invalid) date before here.
- */
 export function dateToSerial(date) {
     const days = (date.getTime() - EPOCH_1900_UTC) / MS_PER_DAY;
-    // Days at or below the phantom (1900-02-28 is day 60 from the nominal epoch) are shifted
-    // one earlier to skip the fake 1900-02-29 that Excel counts at serial 60.
     return days <= PHANTOM_SERIAL ? days - 1 : days;
 }
-/**
- * Convert a 1900-system Excel serial back to a UTC `Date`, accounting for the phantom
- * 1900-02-29 so serial 1 reads as 1900-01-01 (not 1899-12-31) and consecutive serials
- * map to consecutive days.
- */
 export function serialToDate(serial) {
     const dayOffset = serial < PHANTOM_SERIAL ? serial + 1 : serial;
     return new Date(EPOCH_1900_UTC + dayOffset * MS_PER_DAY);
 }
-/**
- * Whether a number-format code renders its value as a date or time. A format is a date
- * format when, once its non-formatting sections are removed — bracketed color/locale/
- * condition directives, quoted literals, and escaped characters — any of the date/time
- * placeholder letters (`y m d h s`) remain. So `"$"#,##0.00` and `0.00%` are not dates
- * while `yyyy-mm-dd`, `dd/mm/yyyy`, and `[$-409]mmmm d, yyyy` are.
- */
 export function isDateFormat(code) {
     const stripped = code
         .replace(/\[[^\]]*\]/g, '')

package/dist/core/formula.js

@@ -1,68 +1,18 @@
-// OOXML froze its formula-function grammar around Excel 2007. Every function Microsoft has added
-// since — the dynamic-array family, LAMBDA and its helpers, the newer text and logical functions —
-// is persisted in the sheet XML under an `_xlfn.` name-mangling prefix. The prefix is purely an
-// on-disk convention: the model only ever holds the plain, readable name, the writer applies the
-// prefix on the way out, and the reader strips it back on the way in. A writer that omits it emits
-// a formula current Excel silently drops, because the function is unknown under its bare name. This
-// module is the single place that knows the mangling — shared by the xlsx writer and reader like
-// address.ts and date.ts own their domains.
-//
-// It also owns formula *translation*: a spreadsheet fills a formula down or across a range by storing
-// it once on a master cell and marking the rest as shared clones. Reading a clone means recovering the
-// master's formula shifted to the clone's position — relative references move by the row/column
-// offset, absolute (`$`-anchored) parts stay put. That relative-reference arithmetic lives here too.
-//
-// Every pass over a formula shares one hazard: a comma, paren, function name, or cell reference is
-// mere text when it sits inside a string literal, a single-quoted sheet name, or a bracketed
-// structured reference. `skipOpaque` is the single owner of skipping those regions — every pass drives
-// its string/quote/bracket handling through it, so the rule lives in one place. The stateless passes
-// (function-name and cell-reference rewriting) ride `scanFormula`, which copies the opaque regions
-// verbatim and hands each code run between them to a transform. `mangleParams` is the deliberate
-// exception: LET/LAMBDA parameter scope opens and closes at paren boundaries, state `scanFormula`'s
-// per-run transform cannot carry, so it runs its own forward walk — still deferring to `skipOpaque`.
 import { columnToNumber, numberToColumn } from './address.js';
 import { MODERN_FUNCTIONS } from './modern-functions.js';
 const XLFN = '_xlfn.';
 const XLPM = '_xlpm.';
-/**
- * Quote a sheet name for use in a reference exactly when Excel would: a name that is not a plain
- * identifier — or that would read as a cell address — is wrapped in single quotes with its internal
- * quotes doubled, and a simple name is left bare. Shared by everything that *builds* a qualified
- * reference: the `_FilterDatabase` name the writer derives from an autofilter, and the `.xlsb`
- * reader's Ptg decoder, which has only a sheet index to work from and must spell the prefix itself.
- *
- * `last` names the far end of a 3-D span (`Data:More!A1`). A span is quoted as a whole or not at all,
- * because the quotes delimit the sheet *reference* rather than either name — so one awkward endpoint
- * puts both inside the quotes.
- */
 export function quoteSheetName(name, last) {
     const names = last === undefined ? [name] : [name, last];
     const joined = names.join(':');
-    // A sheet name cannot itself contain a colon, so joining first and quoting the result is
-    // unambiguous.
     return names.every(isBareSheetName) ? joined : `'${joined.replace(/'/g, "''")}'`;
 }
 function isBareSheetName(name) {
     return /^[A-Za-z_][A-Za-z0-9_.]*$/.test(name) && !/^[A-Za-z]{1,3}\d+$/.test(name);
 }
-// LET and LAMBDA are the only functions that bind names. Their parameter identifiers are persisted
-// under an `_xlpm.` prefix — at the declaration site and at every in-body reference — exactly as the
-// modern functions themselves carry `_xlfn.`. The prefix is scoped: a name bound by one LET/LAMBDA
-// is only prefixed inside that call, so a same-named defined-name reference elsewhere is untouched.
 const SCOPING_FUNCTIONS = new Set(['LET', 'LAMBDA']);
-// A function call is an identifier — dots included, so a dotted name like NORM.DIST is matched whole
-// rather than by its tail — immediately followed by '('. The negative lookbehind rejects a name
-// preceded by an identifier character or '.', so an already-qualified name (`_xlfn.XLOOKUP`) is
-// consumed as a single token whose uppercased form is absent from the set, and is therefore never
-// double-prefixed. Lookbehind rather than a consumed boundary char so adjacent calls
-// (SUM(FILTER(…))) both match.
 const FUNCTION_CALL = /(?<![A-Za-z0-9_.])([A-Za-z_][A-Za-z0-9_.]*)(\s*\()/g;
 const PREFIX = /_xlfn\.|_xlpm\./g;
-// Advance past the opaque region opened at `index`: a double-quoted string literal or a single-quoted
-// sheet name — both honouring the doubled-quote escape (`""`, `''`) — or a bracketed structured
-// reference, which may nest (`Table[[#Data],[Col]]`). Returns the index just past the region, or
-// `index` unchanged when no opaque region opens there. Inside any of the three a comma, paren, function
-// name, or cell reference is inert, so every pass over a formula skips them through this one function.
 function skipOpaque(formula, index) {
     const opener = formula[index];
     const n = formula.length;
@@ -98,11 +48,6 @@ function skipOpaque(formula, index) {
     }
     return index;
 }
-// Rewrite a formula's code while copying its opaque regions — string literals, single-quoted sheet
-// names, bracketed structured references — verbatim. `transform` sees each maximal run of code between
-// those regions and returns its replacement; the opaque text is never handed to it, so a literal like
-// `"FILTER("` is never mistaken for a call and a `,` inside a structured reference never reads as a
-// separator. Concatenating the transformed runs with the copied regions reproduces the formula.
 function scanFormula(formula, transform) {
     let out = '';
     let codeStart = 0;
@@ -122,29 +67,15 @@ function scanFormula(formula, transform) {
     }
     return out + transform(formula.slice(codeStart));
 }
-/**
- * Prefix every modern function called by its plain name with `_xlfn.` so Excel accepts the stored
- * formula. Names already prefixed are left alone (never doubled), unknown/legacy functions pass
- * through untouched, and opaque regions (string literals, sheet names, structured references) are
- * preserved verbatim. No other rewriting occurs — in particular no `@` implicit-intersection operator
- * is ever introduced.
- */
 export function mangleFunctions(formula) {
     return scanFormula(formula, (code) => code.replace(FUNCTION_CALL, (whole, name, open) => MODERN_FUNCTIONS.has(name.toUpperCase()) ? `${XLFN}${name}${open}` : whole));
 }
-/**
- * Strip the `_xlfn.` function prefix and the `_xlpm.` LET-parameter prefix back to the plain names,
- * so the model holds the readable form regardless of how a file stored it. Opaque regions (string
- * literals, sheet names, structured references) are left untouched.
- */
 export function unmangleFunctions(formula) {
     return scanFormula(formula, (code) => code.replace(PREFIX, ''));
 }
 const NAME_START = /[A-Za-z_]/;
 const NAME_CHAR = /[A-Za-z0-9_.]/;
 const WHITESPACE = /\s/;
-// Advance past an identifier — dots included, matching FUNCTION_CALL — starting at `i`, or return `i`
-// unchanged when no identifier begins there.
 function readName(formula, i) {
     if (!NAME_START.test(formula[i] ?? ''))
         return i;
@@ -153,12 +84,6 @@ function readName(formula, i) {
         j += 1;
     return j;
 }
-/**
- * From the index of a call's opening paren, find the matching close and the `[start, end)` ranges of
- * its top-level, comma-separated arguments. Nested parens are tracked by depth; opaque regions (string
- * literals, sheet names, structured references) are skipped whole so their commas do not split an
- * argument.
- */
 function parseCall(formula, open) {
     const args = [];
     const n = formula.length;
@@ -196,8 +121,6 @@ function parseCall(formula, open) {
     args.push([argStart, n]);
     return { close: n, args };
 }
-// Extract the single, unprefixed identifier occupying an argument range, or `undefined` when the
-// range is not one clean name (whitespace-trimmed) — a malformed binding we decline to touch.
 function boundName(formula, [start, end]) {
     let s = start;
     let e = end;
@@ -210,8 +133,6 @@ function boundName(formula, [start, end]) {
     const name = formula.slice(s, e);
     return name.startsWith(XLPM) ? undefined : name;
 }
-// The parameter names a LET/LAMBDA call binds. LAMBDA binds every argument but its last (the body);
-// LET binds the even-indexed arguments up to but excluding its last (the calculation).
 function parameterNames(formula, keyword, args) {
     const names = new Set();
     const isLambda = keyword === 'LAMBDA';
@@ -224,23 +145,10 @@ function parameterNames(formula, keyword, args) {
     }
     return names;
 }
-/**
- * Prefix every LET/LAMBDA parameter identifier with `_xlpm.` — at its declaration and at each
- * reference within the binding call's parentheses — so Excel accepts the stored formula. The prefix
- * is lexically scoped: a name is only rewritten inside the call that binds it, opaque regions are
- * copied verbatim, and a lambda-valued parameter used as a call (`f(…)`) is prefixed too. Formulas
- * with no LET/LAMBDA pass through unchanged.
- */
 export function mangleParams(formula) {
-    // This is the one pass scanFormula cannot serve: it must know when a paren opens a LET/LAMBDA scope
-    // and when the matching paren closes it, so it carries frame state across the code between opaque
-    // regions rather than transforming each run in isolation. It still defers to skipOpaque, keeping the
-    // opaque-skipping rule in one place even though the forward walk here is bespoke.
     let out = '';
     let i = 0;
     const n = formula.length;
-    // A stack of active bindings, each expiring exactly at its owner call's close paren. Nested
-    // LET/LAMBDA push inner frames that pop first, so shadowing resolves to the same prefix anyway.
     const frames = [];
     const inScope = (name) => frames.some((frame) => frame.names.has(name));
     while (i < n) {
@@ -269,45 +177,20 @@ export function mangleParams(formula) {
         const heads = formula[k] === '(';
         if (heads && SCOPING_FUNCTIONS.has(name.toUpperCase()) && !inScope(name)) {
             const { close, args } = parseCall(formula, k);
-            // The keyword stays at the outer scope; its parameters take effect inside the parens.
             out += formula.slice(i, k + 1);
             frames.push({ end: close, names: parameterNames(formula, name.toUpperCase(), args) });
             i = k + 1;
             continue;
         }
-        // Any other identifier — a bare reference, an ordinary call, or a lambda-valued parameter call.
-        // In-scope names (declaration sites included, as they lie inside their own binding's parens) take
-        // the prefix; the rest pass through. Call arguments are covered by the continuing scan, so a
-        // nested LET/LAMBDA within them is still seen.
         out += inScope(name) ? `${XLPM}${name}` : name;
         i = nameEnd;
     }
     return out;
 }
-/**
- * Mangle a model formula into its on-disk form: LET/LAMBDA parameter names first (`_xlpm.`), then the
- * modern-function prefix (`_xlfn.`). Ordering matters — parameter mangling reads the plain LET/LAMBDA
- * names before the function pass qualifies them. The inverse for both prefixes is unmangleFunctions.
- */
 export function mangleFormula(formula) {
     return mangleFunctions(mangleParams(formula));
 }
-// A relative cell reference to shift: an optional `$`, then 1–3 uppercase column letters, an optional
-// `$`, then the row digits (capped at seven — Excel's last row is 1048576). The column is uppercase-
-// only because Excel stores it that way and so a lowercase defined name is never mistaken for a
-// reference. The lookbehind rejects a reference glued to a preceding name character or '.', so the
-// `A1` inside `_xlfn.A1` or a defined name `FOO_A1` is left alone; the lookahead rejects one continued
-// by a name character, opening a call `(`, or preceding a sheet `!` — a token before `!` is the sheet
-// name (`Q1!A1`), not a cell. Applied per code run, where opaque regions have already been stripped.
 const CELL_REFERENCE = /(?<![A-Za-z0-9_.])(\$?)([A-Z]{1,3})(\$?)([0-9]{1,7})(?![A-Za-z0-9_.!(])/g;
-/**
- * Shift every relative cell reference in a formula by `colDelta` columns and `rowDelta` rows, leaving
- * absolute (`$`-anchored) axes fixed. This is how a shared-formula clone recovers its own formula from
- * the master's: a master `A1*2` shared one row down reads back as `A2*2`, and `$A$1*B1` shared one row
- * and one column across as `$A$1*C2`. String literals, single-quoted sheet names, and bracketed
- * structured references are copied verbatim, and a sheet-qualified reference shifts the cell while its
- * sheet name is untouched. Function names and defined names carry no row digits, so they pass through.
- */
 export function translateFormula(formula, colDelta, rowDelta) {
     if (colDelta === 0 && rowDelta === 0)
         return formula;

package/dist/core/grid-edits.js

@@ -1,16 +1,8 @@
-// Structural-edit machinery: the splice arithmetic that inserts or deletes whole rows and columns
-// and keeps everything anchored to the grid moving in step — line metadata, merged ranges, tables,
-// anchored images, and shared-formula clones. It is isolated from Worksheet because it is pure grid
-// mechanics: it holds the sheet's storage containers by reference and mutates them in place, and
-// touches none of the public cell API. Worksheet builds the cells an insert introduces, then hands
-// the pre-built rows (or the raw column values) here for the shift.
 import { decodeAddress, decodeRange, encodeAddress } from './address.js';
 import { Cell, copyCellContent } from './cell.js';
 import { replaceContents } from './containers.js';
 import { isOneCellAnchor } from './image.js';
 import { isSharedFormulaValue } from './value.js';
-// The shift rule shared by every re-anchoring pass: a coordinate before the edit stays put, one at or
-// after the edited span shifts by `delta`, and one inside a deleted span clamps to the cut line (`start`).
 function shiftIndex(v, start, count, delta) {
     return v < start ? v : v >= start + count ? v + delta : start;
 }
@@ -31,10 +23,6 @@ export class GridEdits {
         this.#tables = storage.tables;
         this.#images = storage.images;
     }
-    // Apply a delete-then-insert to the row grid: surviving rows below the edit shift by
-    // `inserted.length - count`, deleted rows drop out, and the pre-built inserted rows land at `start`.
-    // Row metadata and merged ranges shift the same way, so a formatting-only row or a covered merge
-    // stays aligned with the data it describes.
     spliceRows(start, count, inserted) {
         const delta = inserted.length - count;
         const shifted = new Map();
@@ -56,10 +44,6 @@ export class GridEdits {
         this.#shiftImages('row', start, count, delta);
         this.#reanchorSharedFormulas('row', start, count, delta);
     }
-    // Apply a delete-then-insert to the column grid: cells left of the edit stay, cells at or beyond the
-    // deleted span shift by `inserts.length - count` carrying their content, and the inserted column
-    // values materialise as fresh cells at `start`. Column metadata, merges, tables, images, and
-    // shared-formula clones re-anchor the same way.
     spliceColumns(start, count, inserts) {
         const delta = inserts.length - count;
         for (const [row, cols] of this.#rows) {
@@ -91,8 +75,6 @@ export class GridEdits {
         this.#shiftImages('col', start, count, delta);
         this.#reanchorSharedFormulas('col', start, count, delta);
     }
-    // Rebuild a row's cells at a new row index. `Cell` fixes its position at construction, so a moved
-    // row is a fresh set of cells at `destRow` carrying the originals' content.
     #relocateRow(cols, destRow) {
         const moved = new Map();
         for (const [col, cell] of cols) {
@@ -107,11 +89,6 @@ export class GridEdits {
         }
         return moved;
     }
-    // Re-anchor shared-formula clones through a splice on the given axis. A clone stores its master's
-    // absolute address; when the splice shifts the master, that stored address goes stale and the writer
-    // would reject the clone as orphaned. Applying the same shift the grid used keeps each clone pointed
-    // at its master's new cell. A master whose axis coordinate falls in the deleted span clamps to the
-    // cut line like a merge edge — a genuinely orphaned clone the writer then reports legibly.
     #reanchorSharedFormulas(axis, start, count, delta) {
         for (const cols of this.#rows.values()) {
             for (const cell of cols.values()) {
@@ -131,9 +108,6 @@ export class GridEdits {
             }
         }
     }
-    // Shift a line-metadata map (row properties keyed by row, or column properties keyed by column)
-    // through a splice: entries before the edit stay, entries within the deleted span drop, entries
-    // after shift by `delta`. Mutates the map in place.
     #shiftLineProperties(map, start, count, delta) {
         const shifted = new Map();
         for (const [index, value] of map) {
@@ -146,11 +120,6 @@ export class GridEdits {
         for (const [index, value] of shifted)
             map.set(index, value);
     }
-    // Re-anchor merged ranges through a row or column splice. A range wholly before the edit is
-    // untouched; one wholly after shifts by `nInserts - count`; one whose covered rows/columns are
-    // entirely deleted is dropped. A range straddling the cut is a genuinely ambiguous geometry — its
-    // edges are clamped to the cut line as a best effort. Unbounded whole-row/column merges carry no
-    // rectangle and pass through unchanged.
     #shiftMerges(axis, start, count, delta) {
         const shift = (v) => shiftIndex(v, start, count, delta);
         const merges = [];
@@ -173,19 +142,12 @@ export class GridEdits {
         replaceContents(this.#merges, merges);
         replaceContents(this.#mergeRects, rects);
     }
-    // Re-pin the sheet's tables through a splice on the given axis, dropping any table a delete leaves
-    // with no row to occupy. `Table` owns the shift arithmetic; the sheet only prunes the casualties.
     #shiftTables(axis, start, count, delta) {
         const survivors = this.#tables.filter((table) => axis === 'row'
             ? table.shiftRows(start, count, delta)
             : table.shiftColumns(start, count, delta));
         replaceContents(this.#tables, survivors);
     }
-    // Re-pin anchored images through a splice. An anchor point moves like a merge edge: a point before
-    // the cut stays, one at or after it shifts by `delta`, and one inside a deleted span clamps to the
-    // cut line. Grid points are 0-based, so each is converted to the 1-based coordinate the shared
-    // shift arithmetic uses and back. An anchor whose points both move keeps its size; an anchor
-    // straddling the cut grows or shrinks, matching how Excel reflows a picture across inserted rows.
     #shiftImages(axis, start, count, delta) {
         const shiftPoint = (point) => {
             const zeroBased = axis === 'row' ? point.row : point.col;

package/dist/core/image.js

@@ -1,27 +1,11 @@
-// Anchored images: the model for a picture pinned to a worksheet's grid.
-//
-// The image *bytes* live once on the workbook (a small media registry, addressed by a numeric id);
-// a worksheet then anchors that image to a rectangle of cells. Storing the bytes centrally means the
-// same picture used on two sheets — a logo in a header band, say — is one media part, not two.
-/** EMUs per pixel at Excel's notional 96 DPI (914400 EMU/inch ÷ 96 px/inch). The conversion is
- * DPI-independent by construction: a pixel extent is a fixed physical size regardless of screen. */
 export const PX_TO_EMU = 9525;
-/** Narrow an anchor to its one-cell (fixed-extent) form; the complement is {@link TwoCellAnchor}. */
 export function isOneCellAnchor(anchor) {
     return 'ext' in anchor;
 }
-// Sub-cell anchor geometry. Excel measures a column in characters of the default font (~7 px each at
-// 96 DPI) and a row in points (1/72 inch); a column or row that sets no size falls back to Excel's
-// own defaults. These constants live here, beside the anchor model they serve, rather than in the
-// Worksheet that merely supplies the per-column/row sizes.
 const CHAR_WIDTH_PX = 7;
 const EMU_PER_POINT = 12700;
 const DEFAULT_COL_WIDTH_CHARS = 8.43;
 const DEFAULT_ROW_HEIGHT_POINTS = 15;
-/** Resolve a possibly-fractional anchor point to the cell it floors to plus a sub-cell EMU offset
- * scaled by that cell's real width/height, so `col: 3.5` lands halfway across column 3 regardless of
- * the column's size. An already-integer point keeps a zero offset (unless one was given). The two
- * lookups supply each column/row's size; a size they leave `undefined` falls back to Excel's default. */
 export function resolveAnchorPoint(point, columnWidth, rowHeight) {
     const col = Math.floor(point.col);
     const row = Math.floor(point.row);
@@ -31,8 +15,6 @@ export function resolveAnchorPoint(point, columnWidth, rowHeight) {
     const rowOff = (point.rowOff ?? 0) + Math.round((point.row - row) * rowHeightEmu);
     return { col, row, colOff, rowOff };
 }
-// Leading magic bytes for the raster formats a spreadsheet embeds, most-specific first. Used to infer
-// an extension when the caller supplies none, so a package never declares an `image/undefined` type.
 const IMAGE_MAGIC = [
     { ext: 'png', sig: [0x89, 0x50, 0x4e, 0x47] },
     { ext: 'jpeg', sig: [0xff, 0xd8, 0xff] },
@@ -46,15 +28,8 @@ function sniffImageExtension(data) {
         if (sig.every((b, i) => data[i] === b))
             return ext;
     }
-    // An unrecognised blob still needs a valid media name and content type; png keeps the package
-    // well-formed rather than emitting a `<Default>` with no or a bogus extension.
     return 'png';
 }
-/** Reduce a caller-supplied extension to the bare, lower-case alphanumeric token OOXML expects for a
- * media part's name and `<Default Extension>`. A leading dot (`".png"`), a URL query string
- * (`"png?alt=media"`), or any other separator a real-world filename/URL drags in is stripped to the
- * leading run of alphanumerics; a missing or all-punctuation hint falls back to sniffing the bytes'
- * magic number, so the package is always well-formed. */
 export function normalizeImageExtension(extension, data) {
     if (typeof extension === 'string') {
         const token = extension.toLowerCase().match(/[a-z0-9]+/)?.[0];

package/dist/core/internal.js

@@ -1,29 +1,2 @@
-// The codec's back channel into the model.
-//
-// A reader has to push state into a `Workbook` that no authoring path can produce: a `<dxfs>` table
-// whose indices existing rules already point at, a theme part carried as opaque bytes, a protection
-// credential in finished agile form with no recoverable password. The streaming writer likewise has
-// to drop a row's cells the moment they are serialised. All of that used to be public methods on the
-// model classes — so they shipped in the `.d.ts`, appeared in the generated API reference, and a
-// caller who tried one put the workbook in a state nothing else could reach or repair. There was no
-// authoring/codec boundary at all: the model class *was* the codec's mutation interface.
-//
-// These symbols are that boundary. The operations still live on the classes and still mutate exactly
-// the state they always did — this moves no data — but reaching them requires a symbol that is not on
-// the public barrel and, because `package.json` exposes only the root entry, is not importable from
-// outside the package at all. Inside the tree, the import is the audit trail: `grep` for this module
-// and you have the complete list of code that can restore preserved state.
-//
-// Prefer an ordinary public method whenever a caller could reasonably want the operation. This is for
-// operations that are *only* meaningful mid-deserialisation.
-/**
- * Keys the codec-only operations on `Workbook` and `Worksheet` (see `WorkbookInternals` /
- * `WorksheetInternals`, declared beside their classes).
- */
 export const INTERNAL = Symbol('ts-xlsx codec channel');
-/**
- * Keys a `Cell`'s link to a named cell style — its OOXML `xfId`. A single hidden property rather than
- * a channel object, so it stays a prototype accessor: cells are the one model class allocated in the
- * millions, and a per-instance internals object would be a real cost for state most cells never carry.
- */
 export const NAMED_STYLE_ID = Symbol('ts-xlsx named style link');