@shbernal/ts-xlsx 1.0.3 → 1.2.0

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

@@ -1,7 +1,3 @@
-// The worksheet-body reader: one `xl/worksheets/sheetN.xml` in, its cells/columns/rows/print-setup
-// applied onto a {@link Worksheet}. It is a single streaming pass driving a handful of accumulators
-// (the cell being read, shared-formula masters, an autofilter draft, the current page-break axis) so
-// each element commits its state as it closes. Style indices resolve through the parsed style table.
 import { decodeRange } from '../../core/address.js';
 import { isCustomFilterOperator, } from '../../core/autofilter.js';
 import { INTERNAL } from '../../core/internal.js';
@@ -9,15 +5,9 @@ import { SHEET_PROTECTION_FLAGS, } from '../../core/protection.js';
 import { assignStyleFacets } from '../../core/style.js';
 import { boolPresent, boolStrict, boolTristate, localName, parseXml, } from '../../xml/xml-read.js';
 import { CellAccumulator } from './cell-accumulator.js';
-import { parseColor } from './styles.js';
+import { parseColor } from './color-xml.js';
 const MARGIN_SIDES = ['left', 'right', 'top', 'bottom', 'header', 'footer'];
-// Worksheet elements that commit on their close: a formatted-but-empty `<c/>` and a criteria-free
-// self-closing `<autoFilter/>` are expanded to open+close so each finalises once in onClose. The
-// text-bearing `<f/>`/`<v/>`/`<t/>` are deliberately excluded — an empty one must not commit.
 const WORKSHEET_EMPTY_CLOSES = new Set(['c', 'autoFilter']);
-// Fold a filter column's accumulated `<filters>` or `<customFilters>` state into one criteria value,
-// or null when it carried nothing filterable. A `<filters>` block with no values and no blank flag,
-// or a `<customFilters>` with no predicates, is a no-op that would round-trip as noise, so it drops.
 function pendingFilterCriteria(values, blank, predicates, and) {
     if (values !== null && (values.length > 0 || blank)) {
         return { kind: 'values', values, blank };
@@ -27,12 +17,6 @@ function pendingFilterCriteria(values, blank, predicates, and) {
     }
     return null;
 }
-// Read a <sheetProtection> element back into a SheetProtection — the deserialization mirror of the
-// writer. `sheet="0"` (or "false") means the element records an *un*protected sheet, so nothing is
-// restored. Each flag attribute is the INVERSE of the author's allow-flag ("1" forbids, "0" permits),
-// and only attributes actually present are carried, so an omitted (default-valued) flag stays absent —
-// exactly what the writer emitted. A password credential is preserved verbatim in its agile form
-// (algorithm, hash, salt, spin count); there is no plaintext password to recover, so it is not re-hashed.
 function parseSheetProtection(attrs) {
     if (attrs.sheet === '0' || attrs.sheet === 'false')
         return undefined;
@@ -60,9 +44,6 @@ function parseSheetProtection(attrs) {
     }
     return { flags };
 }
-// Autofilter accumulation. The sheet `<autoFilter ref>` seeds a draft; each `<filterColumn colId>`
-// opens a column whose criteria (`<filters>` values or `<customFilters>` predicates) stream into the
-// draft until `</filterColumn>`, and `</autoFilter>` commits the whole thing to the sheet.
 class AutoFilterAccumulator {
     #ref = null;
     #columns = [];
@@ -71,14 +52,10 @@ class AutoFilterAccumulator {
     #blank = false;
     #predicates = null;
     #and = false;
-    // Seed a draft from the range. (A table's own `<autoFilter>` also matches, but table sheets route
-    // through parseTable, so this only ever sees the sheet-level one.)
     begin(attrs) {
         this.#ref = attrs.ref !== undefined && attrs.ref !== '' ? attrs.ref : null;
         this.#columns = [];
     }
-    // Open a criteria block for one column, offset `colId` from the range's left edge. Reset the
-    // per-column accumulators; whichever child (`<filters>`/`<customFilters>`) opens fills one.
     beginColumn(attrs) {
         this.#colId = attrs.colId !== undefined ? Number(attrs.colId) : -1;
         this.#values = null;
@@ -88,8 +65,6 @@ class AutoFilterAccumulator {
     }
     beginValues(attrs) {
         this.#values = [];
-        // `blank` defaults off when absent, so presence is required first — then it reads as an
-        // on-when-present flag. (`boolPresent` alone would treat the absent attribute as on.)
         this.#blank = attrs.blank !== undefined && boolPresent(attrs.blank);
     }
     addValue(attrs) {
@@ -100,8 +75,6 @@ class AutoFilterAccumulator {
         this.#predicates = [];
         this.#and = attrs.and !== undefined && boolPresent(attrs.and);
     }
-    // The operator attribute defaults to `equal` when absent (per CT_CustomFilter); an operand is
-    // likewise optional. An unrecognised operator drops the predicate rather than guessing.
     addCustom(attrs) {
         if (this.#predicates === null)
             return;
@@ -110,18 +83,12 @@ class AutoFilterAccumulator {
             this.#predicates.push({ operator, val: attrs.val ?? '' });
         }
     }
-    // Assemble this column's criteria from whichever accumulator filled. A column whose colId is
-    // negative, or whose criteria are empty (no values, no blank, no predicates), carries nothing
-    // filterable and is dropped so a re-write stays clean — load-repair, not authoring.
     endColumn() {
         const criteria = pendingFilterCriteria(this.#values, this.#blank, this.#predicates, this.#and);
         if (this.#colId >= 0 && criteria !== null) {
             this.#columns.push({ colId: this.#colId, criteria });
         }
     }
-    // Commit the accumulated autofilter to the sheet. Runs on `</autoFilter>` — including the synthesized
-    // close of a criteria-free self-closing `<autoFilter/>`. Columns whose colId falls outside the range
-    // are dropped here so the strict setter never trips on hostile input.
     commit(sheet) {
         if (this.#ref === null)
             return;
@@ -131,16 +98,11 @@ class AutoFilterAccumulator {
             sheet.autoFilter = { ref: this.#ref, columns: this.#columns.filter((c) => c.colId < width) };
         }
         catch {
-            // unbounded or malformed autofilter range in the source file — ignore it
         }
         this.#ref = null;
         this.#columns = [];
     }
 }
-// Page-break accumulation. `<brk>` elements appear under both `<rowBreaks>` and `<colBreaks>`; a break
-// container's open points the accumulator at that axis's list (null outside any container), so a
-// `<brk>` lands on the right axis, and the matching close clears it. A self-closing
-// `<rowBreaks/>`/`<colBreaks/>` fires no close, so a new open simply reassigns the target.
 class PageBreakAccumulator {
     #target = null;
     begin(target) {
@@ -149,8 +111,6 @@ class PageBreakAccumulator {
     end() {
         this.#target = null;
     }
-    // `id` is the row/column the layout splits before; a non-positive or non-integer id is hostile input
-    // and dropped rather than trusted. A `<brk>` outside any break container has no axis and is ignored.
     add(attrs) {
         if (this.#target === null)
             return;
@@ -167,24 +127,15 @@ class PageBreakAccumulator {
     }
 }
 export function parseWorksheet(xml, sheet, sharedStrings, xfStyles) {
-    // The one `<c>` currently being read: its address/type/style, formula, value, inline text, rich
-    // runs, and the sheet-spanning shared-formula master map. Each `<c>` resets it and commits it.
     const cell = new CellAccumulator();
     let inInlineString = false;
     let capture = false;
     let text = '';
-    // A row with customFormat="1" supplies a default style for its cells that carry no `s`.
     let rowStyle = -1;
     let rowCustomFormat = false;
     const autoFilter = new AutoFilterAccumulator();
     const pageBreaks = new PageBreakAccumulator();
-    // A column's `style` is the default for its cells that carry no style of their own; this
-    // maps a column index to that style index so a bare cell can inherit it (as Excel does,
-    // without stamping every cell). Columns are parsed before any cell references them.
     const columnStyle = new Map();
-    // Commit the cell held in the accumulator, resolving its style from its own `s`, then its row's
-    // (when customFormat), then its column's default — the order Excel applies. Runs on `</c>` close,
-    // including the synthesized close of a self-closing `<c/>` formatted-but-empty cell.
     const finalizeCellFromState = () => {
         const styleIndex = cell.styleIndex >= 0
             ? cell.styleIndex
@@ -216,12 +167,10 @@ export function parseWorksheet(xml, sheet, sharedStrings, xfStyles) {
                     cell.beginInlineString();
                     break;
                 case 'r':
-                    // A run inside a rich inline string. Its `<rPr>` (if any) and `<t>` follow.
                     if (inInlineString)
                         cell.runs.beginRun();
                     break;
                 case 'rPr':
-                    // The run's formatting bundle; its self-closing children stream into the default branch.
                     cell.runs.beginProperties();
                     break;
                 case 'f':
@@ -238,21 +187,14 @@ export function parseWorksheet(xml, sheet, sharedStrings, xfStyles) {
                 case 'evenFooter':
                 case 'firstHeader':
                 case 'firstFooter':
-                    // A `<headerFooter>` child carries its header/footer definition as text (the `&`-prefixed
-                    // section/format tokens, e.g. `&C&"Arial"&G`). Capture it verbatim so a round-trip preserves
-                    // a header image's `&G` picture token and every other formatting directive.
                     capture = true;
                     break;
                 case 'mergeCell':
-                    // A well-formed file never declares overlapping merges; a corrupt one might. Reject the
-                    // bad range at the model boundary, but don't let one abort the whole parse — drop it and
-                    // keep reading the valid geometry.
                     if (attrs.ref !== undefined && attrs.ref !== '') {
                         try {
                             sheet.mergeCells(attrs.ref);
                         }
                         catch {
-                            // overlapping/malformed merge in the source file — skip it
                         }
                     }
                     break;
@@ -299,8 +241,6 @@ export function parseWorksheet(xml, sheet, sharedStrings, xfStyles) {
                     autoFilter.addCustom(attrs);
                     break;
                 default:
-                    // A run's `<rPr>` child (`<b/>`, `<sz>`, `<color>`, `<rFont>`, …) sets one font facet; it
-                    // is self-closing, so it is read here on open. Nothing else uses the default branch.
                     cell.runs.applyProperty(local, attrs);
                     break;
             }
@@ -321,8 +261,6 @@ export function parseWorksheet(xml, sheet, sharedStrings, xfStyles) {
                     cell.setValue(text);
                     break;
                 case 't':
-                    // A `<t>` inside a run is that run's text; a bare `<t>` directly in the `<is>` is a plain
-                    // inline string. A run takes precedence — a run is also inside the inline string.
                     cell.appendText(text, inInlineString);
                     break;
                 case 'r':
@@ -363,27 +301,18 @@ export function parseWorksheet(xml, sheet, sharedStrings, xfStyles) {
         },
     }, { closeEmptyElements: WORKSHEET_EMPTY_CLOSES });
 }
-// Apply one `<sheetPr>` / `<sheetView>` / print-setup child to the sheet. These are the worksheet's
-// layout and print metadata; grouping them here keeps the cell-reading switch a pure dispatch. Each
-// records only what the source carried, so a file missing a facet leaves it unset and a re-write
-// stays byte-clean. Every element here is self-closing (its state is all in attributes), so it is
-// read on open.
 function applySheetProperties(local, attrs, sheet) {
     switch (local) {
         case 'tabColor':
-            // A `<sheetPr>` child.
             sheet.tabColor = parseColor(attrs);
             break;
         case 'outlinePr':
-            // A `<sheetPr>` child.
             if (attrs.summaryBelow !== undefined)
                 sheet.outline.summaryBelow = boolPresent(attrs.summaryBelow);
             if (attrs.summaryRight !== undefined)
                 sheet.outline.summaryRight = boolPresent(attrs.summaryRight);
             break;
         case 'pane':
-            // A `<sheetView>` child recording a frozen (or split) pane. Only a frozen pane maps onto the
-            // model's view; a source without one leaves `view` empty, so a re-write emits no pane.
             if (attrs.state === 'frozen' || attrs.state === 'frozenSplit') {
                 sheet.view.state = 'frozen';
                 if (attrs.xSplit !== undefined)
@@ -395,8 +324,6 @@ function applySheetProperties(local, attrs, sheet) {
             }
             break;
         case 'pageSetUpPr':
-            // The fit-to-page flag, a `<sheetPr>` child. Recorded only when the attribute is present, so a
-            // `<pageSetUpPr>` present for other reasons (e.g. `autoPageBreaks`) leaves `fitToPage` unset.
             if (attrs.fitToPage !== undefined)
                 sheet.pageSetup.fitToPage = boolPresent(attrs.fitToPage);
             break;
@@ -419,8 +346,6 @@ function applyColumn(sheet, attrs, xfStyles, columnStyle) {
     const width = attrs.width !== undefined ? Number(attrs.width) : undefined;
     const hidden = boolStrict(attrs.hidden);
     const styleIndex = attrs.style !== undefined ? Number(attrs.style) : -1;
-    // The column's style resolves to the same facet bundle a cell's does; mirror all of it onto the
-    // column model so `getColumn(i)` reflects the declared default, not just its number format.
     const style = styleIndex >= 0 ? xfStyles[styleIndex] : undefined;
     for (let index = min; index <= max; index++) {
         const column = sheet.getColumn(index);
@@ -437,7 +362,6 @@ function applyColumn(sheet, attrs, xfStyles, columnStyle) {
             column.collapsed = true;
         if (style !== undefined)
             assignStyleFacets(column, style);
-        // Record the column's style so a bare cell in it can inherit the full column format on read.
         if (styleIndex >= 0)
             columnStyle.set(index, styleIndex);
     }
@@ -446,10 +370,6 @@ function applyRow(sheet, attrs) {
     const number = Number(attrs.r);
     if (!Number.isInteger(number) || number < 1)
         return;
-    // A `<row>` that states no attribute at all leaves no format record behind — the handle creates
-    // one only when something is written through it. That is the right reading: a bare `<row r="5"/>`
-    // carries no formatting to round-trip, and fabricating an empty record for it would put row 5 in
-    // the used range on the strength of an element that says nothing.
     const row = sheet.getRow(number);
     if (attrs.ht !== undefined && attrs.customHeight !== '0') {
         const height = Number(attrs.ht);
@@ -466,9 +386,6 @@ function applyRow(sheet, attrs) {
     if (boolStrict(attrs.collapsed))
         row.collapsed = true;
 }
-// Read the `<printOptions>` boolean toggles back onto the model, storing only the ones the source
-// carried so a re-write stays byte-clean. An OOXML boolean is `1`/`true` for on and `0`/`false` for
-// off; a present-but-unrecognised token is dropped rather than coerced.
 function applyPrintOptions(printOptions, attrs) {
     const horizontalCentered = boolTristate(attrs.horizontalCentered);
     if (horizontalCentered !== undefined)
@@ -496,10 +413,6 @@ function applyMargins(margins, attrs) {
             margins[side] = value;
     }
 }
-// Read the `<pageSetup>` print-scaling attributes back onto the model, setting only those the
-// source carried so a re-write stays byte-clean. Numeric attributes that fail to parse are
-// dropped rather than stored as NaN; the enumerated ones are trusted verbatim (an unexpected token
-// round-trips harmlessly as an unknown string).
 function applyPageSetup(pageSetup, attrs) {
     const num = (raw) => {
         if (raw === undefined)