@shbernal/ts-xlsx 3.1.0 → 3.2.0

package/dist/io/csv/delimiter.js

@@ -1,6 +1,18 @@
 import { quoted } from '../../errors.js';
+const RESERVED = new Set(['"', '\r', '\n']);
 export function assertDelimiter(delimiter) {
     if (delimiter.length !== 1) {
         throw new RangeError(`CSV delimiter must be a single character, got ${quoted(delimiter)}`);
     }
+    if (RESERVED.has(delimiter)) {
+        throw new RangeError(`CSV delimiter ${quoted(delimiter)} is reserved: a quote opens a quoted field, and CR and LF end a row`);
+    }
+}
+export function assertRowDelimiter(rowDelimiter, delimiter) {
+    if (rowDelimiter === '') {
+        throw new RangeError('CSV row delimiter must not be empty');
+    }
+    if (rowDelimiter.includes(delimiter) || rowDelimiter.includes('"')) {
+        throw new RangeError(`CSV row delimiter ${quoted(rowDelimiter)} must contain neither the field delimiter ${quoted(delimiter)} nor a quote`);
+    }
 }

package/dist/io/csv/errors.d.ts

@@ -0,0 +1,14 @@
+import { XlsxError } from '../../errors.ts';
+/**
+ * Thrown when CSV text parses but cannot become a worksheet: a record with more fields than a sheet
+ * has columns, or more records than it has rows.
+ *
+ * CSV has no malformed markup to reject, since any text splits into fields somehow, so the only way a
+ * file fails is by not fitting the grid. That is still the file's fault rather than the caller's,
+ * which is why it is this error and not the `RangeError` the grid raises for an authored cell out of
+ * bounds.
+ */
+export declare class CsvParseError extends XlsxError {
+    readonly name = "CsvParseError";
+    readonly code = "malformed-input";
+}

package/dist/io/csv/errors.js

@@ -0,0 +1,5 @@
+import { XlsxError } from '../../errors.js';
+export class CsvParseError extends XlsxError {
+    name = 'CsvParseError';
+    code = 'malformed-input';
+}

package/dist/io/csv/read.d.ts

@@ -11,5 +11,10 @@ export interface CsvReadOptions {
     /** Name for the single worksheet produced; defaults to `"Sheet1"`. */
     readonly sheetName?: string;
 }
-/** Parse CSV text (or UTF-8 bytes) into a workbook holding a single worksheet. */
+/**
+ * Parse CSV text (or UTF-8 bytes) into a workbook holding a single worksheet.
+ *
+ * @throws {CsvParseError} if a record has more fields than a worksheet has columns, or the data
+ *   records outnumber a worksheet's rows.
+ */
 export declare function readCsv(input: string | Uint8Array, options?: CsvReadOptions): Workbook;

package/dist/io/csv/read.js

@@ -1,10 +1,12 @@
+import { MAX_COLUMN, MAX_ROW } from '../../core/address.js';
 import { Workbook } from '../../core/workbook.js';
 import { assertDelimiter } from './delimiter.js';
+import { CsvParseError } from './errors.js';
 export function readCsv(input, options = {}) {
     const text = stripBom(typeof input === 'string' ? input : new TextDecoder('utf-8', { ignoreBOM: true }).decode(input));
     const delimiter = options.delimiter ?? ',';
     assertDelimiter(delimiter);
-    let rows = parseCsvRows(text, delimiter);
+    let rows = parseCsvRows(text, delimiter, MAX_ROW + (options.headers ? 1 : 0));
     if (options.headers)
         rows = rows.slice(1);
     const coerce = options.map ?? defaultCsvCoerce;
@@ -16,11 +18,28 @@ export function readCsv(input, options = {}) {
 function stripBom(text) {
     return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
 }
-function parseCsvRows(text, delimiter) {
+function parseCsvRows(text, delimiter, maxRecords) {
     const rows = [];
     let row = [];
     let field = '';
     let inQuotes = false;
+    let atFieldStart = true;
+    const endField = () => {
+        if (row.length === MAX_COLUMN) {
+            throw new CsvParseError(`CSV record ${rows.length + 1} has more than ${MAX_COLUMN} fields, the most columns a worksheet holds`);
+        }
+        row.push(field);
+        field = '';
+        atFieldStart = true;
+    };
+    const endRow = () => {
+        endField();
+        if (rows.length === maxRecords) {
+            throw new CsvParseError(`CSV has more than ${MAX_ROW} data records, the most rows a worksheet holds`);
+        }
+        rows.push(row);
+        row = [];
+    };
     for (let i = 0; i < text.length; i++) {
         const ch = text.charAt(i);
         if (inQuotes) {
@@ -38,45 +57,43 @@ function parseCsvRows(text, delimiter) {
             }
             continue;
         }
-        if (ch === '"') {
+        if (ch === '"' && atFieldStart) {
             inQuotes = true;
+            atFieldStart = false;
         }
         else if (ch === delimiter) {
-            row.push(field);
-            field = '';
+            endField();
         }
         else if (ch === '\n') {
-            row.push(field);
-            rows.push(row);
-            row = [];
-            field = '';
+            endRow();
         }
         else if (ch === '\r') {
-            if (text[i + 1] !== '\n') {
-                row.push(field);
-                rows.push(row);
-                row = [];
-                field = '';
-            }
+            if (text[i + 1] !== '\n')
+                endRow();
         }
         else {
             field += ch;
+            atFieldStart = false;
         }
     }
-    row.push(field);
     const trailingNewline = text.endsWith('\n') || text.endsWith('\r');
-    if (!(trailingNewline && row.length === 1 && row[0] === ''))
-        rows.push(row);
+    if (!(trailingNewline && row.length === 0 && field === ''))
+        endRow();
     return rows;
 }
 const NUMERIC = /^[-+]?(\d+\.?\d*|\.\d+)([eE][-+]?\d+)?$/;
 const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+const MAX_EXACT_SIGNIFICANT_DIGITS = 15;
 function defaultCsvCoerce(field) {
     if (field === '')
         return null;
-    if (NUMERIC.test(field)) {
+    const numeric = NUMERIC.exec(field);
+    if (numeric) {
         const value = Number(field);
-        return Number.isFinite(value) && Math.abs(value) <= Number.MAX_SAFE_INTEGER ? value : field;
+        const exact = Number.isFinite(value) &&
+            Math.abs(value) <= Number.MAX_SAFE_INTEGER &&
+            significantDigits(numeric[1] ?? '') <= MAX_EXACT_SIGNIFICANT_DIGITS;
+        return exact ? value : field;
     }
     const iso = ISO_DATE.exec(field);
     if (iso) {
@@ -86,6 +103,9 @@ function defaultCsvCoerce(field) {
     }
     return field;
 }
+function significantDigits(mantissa) {
+    return mantissa.replace('.', '').replace(/^0+/, '').replace(/0+$/, '').length;
+}
 function isoToDate(match) {
     const year = Number(match[1]);
     const month = Number(match[2]);
@@ -93,9 +113,11 @@ function isoToDate(match) {
     const hour = match[4] === undefined ? 0 : Number(match[4]);
     const minute = match[5] === undefined ? 0 : Number(match[5]);
     const second = match[6] === undefined ? 0 : Number(match[6]);
-    if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59) {
+    if (hour > 23 || minute > 59 || second > 59)
         return null;
-    }
-    const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
-    return Number.isNaN(date.getTime()) ? null : date;
+    const date = new Date(0);
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hour, minute, second, 0);
+    const real = date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+    return real ? date : null;
 }

package/dist/io/csv/write.d.ts

@@ -14,9 +14,10 @@ export interface CsvWriteOptions {
     /** Which worksheet to write; defaults to the first. A name matching no sheet throws rather than
      * silently emitting an empty file. */
     readonly sheetName?: string;
-    /** Field separator; defaults to a comma. */
+    /** Field separator; defaults to a comma. A single character other than a quote, CR or LF. */
     readonly delimiter?: string;
-    /** Line separator between rows; defaults to `"\n"`. */
+    /** Line separator between rows; defaults to `"\n"`. Not empty, and containing neither the field
+     * delimiter nor a quote. A field that contains it is quoted. */
     readonly rowDelimiter?: string;
     /**
      * An Excel number-format code (e.g. `"yyyy-mm-dd"`, `"d mmm yy hh:mm"`) for Date cells; without it
@@ -39,12 +40,18 @@ export interface CsvWriteOptions {
      * still applied to the returned text. */
     readonly map?: (value: CellValue, index: number) => string;
 }
-/** The logical CSV text of one worksheet: no BOM, no byte encoding. */
+/**
+ * The logical CSV text of one worksheet: no BOM, no byte encoding. Line N holds row N, so an empty
+ * row before the last populated one is an empty line.
+ *
+ * @throws {RangeError} if `delimiter` or `rowDelimiter` is one the output could not be split on.
+ */
 export declare function writeCsvText(workbook: Workbook, options?: CsvWriteOptions): string;
 /**
  * The CSV bytes of one worksheet in the requested encoding, with a UTF-8 BOM by default.
  *
  * @throws {AuthoringError} if a field holds an unpaired surrogate and the encoding is UTF-8, which
  * cannot represent one. The alternative is a silent U+FFFD substitution.
+ * @throws {RangeError} on a delimiter {@link writeCsvText} refuses.
  */
 export declare function writeCsv(workbook: Workbook, options?: CsvWriteOptions): Uint8Array;

package/dist/io/csv/write.js

@@ -1,28 +1,33 @@
 import { formatSerialDate } from '../../core/date-format.js';
-import { cellValueToText, isDataTableFormulaValue, isFormulaValue, isSharedFormulaValue, } from '../../core/value.js';
+import { cellValueToText, isArrayFormulaValue, isDataTableFormulaValue, isFormulaValue, isSharedFormulaValue, } from '../../core/value.js';
 import { AuthoringError, unrepresentable } from '../../errors.js';
-import { assertDelimiter } from './delimiter.js';
+import { assertDelimiter, assertRowDelimiter } from './delimiter.js';
 const UTF8_BOM = Uint8Array.of(0xef, 0xbb, 0xbf);
 export function writeCsvText(workbook, options = {}) {
     const sheet = selectSheet(workbook, options.sheetName);
     const delimiter = options.delimiter ?? ',';
     assertDelimiter(delimiter);
     const rowDelimiter = options.rowDelimiter ?? '\n';
+    assertRowDelimiter(rowDelimiter, delimiter);
     const lines = [];
-    for (const { cells } of sheet.rows()) {
+    for (const row of sheet.rows()) {
         let width = 0;
         const byColumn = new Map();
-        for (const cell of cells) {
+        for (const cell of row.cells) {
             byColumn.set(cell.col, cell);
             if (cell.col > width)
                 width = cell.col;
         }
+        if (width === 0)
+            continue;
         const fields = [];
         for (let column = 1; column <= width; column++) {
             const value = byColumn.get(column)?.value ?? null;
             const text = options.map ? options.map(value, column - 1) : csvFieldText(value, options);
-            fields.push(quoteField(text, delimiter));
+            fields.push(quoteField(text, delimiter, rowDelimiter));
         }
+        while (lines.length < row.number - 1)
+            lines.push('');
         lines.push(fields.join(delimiter));
     }
     return lines.join(rowDelimiter);
@@ -79,13 +84,17 @@ function csvFieldText(value, options) {
     if (value instanceof Date && options.dateFormat !== undefined) {
         return formatSerialDate(value, options.dateFormat, options.dateUTC ?? false);
     }
-    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
+    if (isFormulaValue(value) ||
+        isSharedFormulaValue(value) ||
+        isArrayFormulaValue(value) ||
+        isDataTableFormulaValue(value)) {
         return value.result === undefined ? '' : csvFieldText(value.result, options);
     }
     return cellValueToText(value);
 }
-function quoteField(field, delimiter) {
+function quoteField(field, delimiter, rowDelimiter) {
     if (field.includes(delimiter) ||
+        field.includes(rowDelimiter) ||
         field.includes('"') ||
         field.includes('\n') ||
         field.includes('\r')) {

package/dist/io/opc/part-paths.js

@@ -23,11 +23,11 @@ export function relativePartPath(fromPath, toPath) {
     return [...Array(up).fill('..'), ...toSegments.slice(common)].join('/');
 }
 export function resolveRelativePart(basePart, target) {
-    if (target.startsWith('/'))
-        return target.slice(1);
-    const baseDir = basePart.slice(0, basePart.lastIndexOf('/') + 1);
+    const joined = target.startsWith('/')
+        ? target
+        : `${basePart.slice(0, basePart.lastIndexOf('/') + 1)}${target}`;
     const out = [];
-    for (const segment of `${baseDir}${target}`.split('/')) {
+    for (const segment of joined.split('/')) {
         if (segment === '' || segment === '.')
             continue;
         if (segment === '..')

package/dist/io/opc/read-opc.d.ts

@@ -5,6 +5,10 @@ export interface PackageAccessors {
     partText: (path: string) => string | undefined;
     /** A part's raw bytes, or undefined when the package holds no such part. */
     partBytes: (path: string) => Uint8Array | undefined;
+    /** The package's own spelling of the part the other two would answer for `path`, or undefined when
+     * there is none: the key an editor replaces or deletes, so it acts on the entry a read found rather
+     * than adding a second one beside it. */
+    partKey: (path: string) => string | undefined;
 }
 /** A spreadsheet package opened for reading: inflated under the read bound, its parts bound to
  * accessors, its office document located through the package's own relationship graph, and that

package/dist/io/opc/read-opc.js

@@ -4,6 +4,7 @@ import { openElements } from '../../xml/xml-read.js';
 import { extensionOf, relsPathFor, resolveRelativePart } from './part-paths.js';
 import { DEFAULT_MAX_UNCOMPRESSED } from './read-options.js';
 import { inflateSpreadsheetPackage } from './sniff-format.js';
+import { transitionalRelationshipType } from './strict-relationships.js';
 export function openSpreadsheetPackage(data, maxUncompressedBytes) {
     const files = inflateSpreadsheetPackage(data, maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED);
     const pkg = packageAccessors(files);
@@ -20,18 +21,23 @@ function conventionalDocument(pkg) {
 }
 export function packageAccessors(files) {
     const folded = new Map();
-    for (const [path, bytes] of Object.entries(files)) {
+    for (const path of Object.keys(files)) {
         const key = path.toLowerCase();
         if (!folded.has(key))
-            folded.set(key, bytes);
+            folded.set(key, path);
     }
-    const lookup = (path) => files[path] ?? folded.get(path.toLowerCase());
+    const partKey = (path) => files[path] === undefined ? folded.get(path.toLowerCase()) : path;
+    const lookup = (path) => {
+        const key = partKey(path);
+        return key === undefined ? undefined : files[key];
+    };
     return {
         partText: (path) => {
             const bytes = lookup(path);
             return bytes === undefined ? undefined : strFromU8(bytes);
         },
         partBytes: lookup,
+        partKey,
     };
 }
 export function parseRelationshipRecords(xml) {
@@ -40,7 +46,7 @@ export function parseRelationshipRecords(xml) {
         if (attrs.Id !== undefined && attrs.Type !== undefined && attrs.Target !== undefined) {
             records.push({
                 id: attrs.Id,
-                type: attrs.Type,
+                type: transitionalRelationshipType(attrs.Type),
                 target: attrs.Target,
                 external: attrs.TargetMode === 'External',
             });

package/dist/io/opc/strict-relationships.d.ts

@@ -0,0 +1,2 @@
+/** A relationship type in its Transitional spelling: a Strict one translated, any other as it is. */
+export declare function transitionalRelationshipType(type: string): string;

package/dist/io/opc/strict-relationships.js

@@ -0,0 +1,12 @@
+const STRICT_RELATIONSHIPS = 'http://purl.oclc.org/ooxml/officeDocument/relationships/';
+const TRANSITIONAL_RELATIONSHIPS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/';
+const RENAMED = new Map([
+    ['extendedProperties', 'extended-properties'],
+    ['customProperties', 'custom-properties'],
+]);
+export function transitionalRelationshipType(type) {
+    if (!type.startsWith(STRICT_RELATIONSHIPS))
+        return type;
+    const name = type.slice(STRICT_RELATIONSHIPS.length);
+    return `${TRANSITIONAL_RELATIONSHIPS}${RENAMED.get(name) ?? name}`;
+}

package/dist/io/read-policy/column-budget.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A per-sheet allowance of column touches, spent by each column run the reader applies.
+ *
+ * A run past the allowance is truncated, and one starting past it is dropped, rather than the read
+ * being refused: that is the stance every reader already takes on an out-of-grid run, and it means a
+ * hostile file loses formatting it could not have meant while a real one is untouched.
+ */
+export declare class ColumnRecordBudget {
+    #private;
+    /** The last column of `[first, last]` this sheet can still afford, or `undefined` when none is. */
+    take(first: number, last: number): number | undefined;
+}
+/**
+ * The columns of a declared run `[first, last]`, one-based, that a sheet actually applies, or
+ * `undefined` for a run that applies to none: one starting past the grid, an empty one, or one the
+ * budget can no longer afford.
+ *
+ * Beside the budget because the two decisions are one decision. The XML readers each had their own
+ * copy, and the copies had already drifted: one tested `first > MAX_COLUMN` and the other did not,
+ * which happened not to matter only because `budget.take` returns `undefined` when `first > last`, an
+ * accident of that method's contract rather than an agreement between the readers.
+ */
+export declare function clampColumnSpan(first: number, last: number, budget: ColumnRecordBudget): {
+    first: number;
+    last: number;
+} | undefined;

package/dist/io/{xlsx → read-policy}/column-budget.js

@@ -1,6 +1,4 @@
 import { MAX_COLUMN } from '../../core/address.js';
-import { numInteger } from '../../xml/xml-attrs.js';
-import {} from '../../xml/xml-scan.js';
 const MAX_COLUMN_RECORD_TOUCHES = MAX_COLUMN * 4;
 export class ColumnRecordBudget {
     #remaining = MAX_COLUMN_RECORD_TOUCHES;
@@ -12,11 +10,9 @@ export class ColumnRecordBudget {
         return affordable;
     }
 }
-export function takeColumnSpan(attrs, budget) {
-    const first = numInteger(attrs.min, 1);
-    const declared = numInteger(attrs.max, 1);
-    if (first === undefined || declared === undefined || first > MAX_COLUMN)
+export function clampColumnSpan(first, last, budget) {
+    if (first > MAX_COLUMN)
         return undefined;
-    const last = budget.take(first, Math.min(declared, MAX_COLUMN));
-    return last === undefined ? undefined : { first, last };
+    const affordable = budget.take(first, Math.min(last, MAX_COLUMN));
+    return affordable === undefined ? undefined : { first, last: affordable };
 }

package/dist/io/read-policy/read-repair.d.ts

@@ -0,0 +1,74 @@
+import { type FormulaPlacement } from '../../core/array-formula-ranges.ts';
+import type { Worksheet } from '../../core/worksheet.ts';
+/**
+ * A sheet name from a file, rewritten into one the model will accept.
+ *
+ * Excel's own repair, in the order the constraints interact: forbidden characters go first (they
+ * can be anywhere), then the length ceiling, then the apostrophe rule *again*, because truncating
+ * can expose an interior apostrophe at the new edge. An empty result becomes `Sheet{n}`, and a
+ * collision takes a ` (2)` suffix that is itself made to fit inside the 31-character limit.
+ *
+ * @param taken the lower-cased names already in the workbook; sheet names collide
+ *   case-insensitively, which is the comparison `Workbook.getWorksheet` makes.
+ */
+export declare function repairSheetName(name: string, taken: ReadonlySet<string>): string;
+/**
+ * A workbook's declared sheets in order, each carrying the name the model will accept: repaired by
+ * {@link repairSheetName} against every name repaired before it.
+ *
+ * Both codecs declare their sheets as an ordered list and both have to know the repaired names before
+ * anything cites a sheet by position, since a scoped defined name and a 3-D reference both index into
+ * that order. The loop threading the taken set through the list is one loop, so it is written once.
+ */
+export declare function repairedSheetNames<T extends {
+    readonly name: string;
+}>(declared: readonly T[]): T[];
+/**
+ * Read a sheet whose array formulas cannot stand as Excel repairs it (`core/array-formula-ranges.ts`). A
+ * file is free to carry an array formula whose range holds another formula, or shares a cell with another
+ * array formula's range, and the writer refuses both, since Excel offers to repair such a package.
+ *
+ * Excel 16.0 keeps the array formula decided first. A formula inside its range loses its formula and its
+ * value, keeping its style, and a shared formula whose master that was loses its formula too, keeping its
+ * value; an array formula whose range only shares cells with it loses its formula, keeping its value. The
+ * value Excel then shows in a cell it emptied is what the kept array formula computes there, which the
+ * library does not compute, so the cell is left empty.
+ */
+export declare function admitArrayRanges(sheet: Worksheet): void;
+/** What Excel's repair takes from a sheet whose array formulas cannot stand. */
+export interface ArrayRangeRepair {
+    /** Formulas whose cell lies in the range of an array formula kept: each loses its whole cell. */
+    readonly cellsRemoved: FormulaPlacement[];
+    /**
+     * Array formulas whose own cell lies in no range kept but whose range shares a cell with one: each loses
+     * its formula and keeps the value it cached.
+     */
+    readonly formulasRemoved: FormulaPlacement[];
+}
+/**
+ * What Excel's repair takes from the sheet, deciding in reading order: an array formula keeps its range
+ * unless that range shares a cell with a range kept before it. A formula of any kind whose cell lies in a
+ * kept range loses the cell; an array formula whose range shares a cell with a kept range, its own cell
+ * outside it, loses its formula and keeps its value. What is left holds no conflict.
+ *
+ * Excel 16.0 (build 20326) repaired B1:B3 holding a plain formula, or an array formula of its own, in B2
+ * by keeping B1's range and removing B2's "cell information", and B1:C2 beside A2:B3 by keeping B1's range
+ * and removing A2's "formula", its value left (`test/corpus/fixtures/excel-oracle/array-formula-ranges.json`).
+ * An array formula's own cell is the first of its range in reading order, so a range is always decided
+ * before any cell it holds, and a range whose formula was taken claims none.
+ */
+export declare function arrayRangeRepair(placements: Iterable<FormulaPlacement>): ArrayRangeRepair;
+/**
+ * Run a model call that is being handed foreign input, and answer `undefined` where the model
+ * refuses it.
+ *
+ * The three caught types are the three a model method raises *about its argument*: an
+ * `AuthoringError` for a composite that cannot exist, and the native `RangeError` / `SyntaxError`
+ * the taxonomy assigns to a single scalar that is out of range or does not parse. Every one of them
+ * is a statement about the caller, and on this path the caller is a file.
+ *
+ * Nothing else is caught. An `XlsxError` raised by a layer below is a real failure of the read and
+ * keeps its identity; an `InternalError` is a bug of ours and must not be swallowed by a reader
+ * being tolerant about somebody else's file.
+ */
+export declare function admitting<T>(build: () => T): T | undefined;

package/dist/io/read-policy/read-repair.js

@@ -0,0 +1,119 @@
+import { tryDecodeAnchoredRange } from '../../core/address.js';
+import { formulaPlacement } from '../../core/array-formula-ranges.js';
+import { INVALID_SHEET_NAME_CHARS, MAX_SHEET_NAME_LENGTH } from '../../core/limits.js';
+import { MergeIndex } from '../../core/merge-index.js';
+import { isFormulaValue, isSharedFormulaValue } from '../../core/value.js';
+import { AuthoringError } from '../../errors.js';
+const INVALID_SHEET_NAME_CHARS_GLOBAL = new RegExp(INVALID_SHEET_NAME_CHARS.source, 'g');
+export function repairSheetName(name, taken) {
+    const stripped = trimApostrophes(name.replace(INVALID_SHEET_NAME_CHARS_GLOBAL, '')).slice(0, MAX_SHEET_NAME_LENGTH);
+    const base = trimApostrophes(stripped);
+    if (base.length === 0)
+        return firstFree((n) => `Sheet${n}`, taken);
+    if (!taken.has(base.toLowerCase()))
+        return base;
+    return firstFree((n) => withSuffix(base, ` (${n})`), taken, 2);
+}
+export function repairedSheetNames(declared) {
+    const taken = new Set();
+    return declared.map((entry) => {
+        const name = repairSheetName(entry.name, taken);
+        taken.add(name.toLowerCase());
+        return { ...entry, name };
+    });
+}
+function trimApostrophes(name) {
+    return name.replace(/^'+/, '').replace(/'+$/, '');
+}
+function firstFree(candidate, taken, from = 1) {
+    for (let n = from;; n++) {
+        const name = candidate(n);
+        if (!taken.has(name.toLowerCase()))
+            return name;
+    }
+}
+function withSuffix(base, suffix) {
+    const room = MAX_SHEET_NAME_LENGTH - suffix.length;
+    return trimApostrophes(base.slice(0, room)) + suffix;
+}
+export function admitArrayRanges(sheet) {
+    const placements = [];
+    for (const { cells } of sheet.rows()) {
+        for (const cell of cells) {
+            const placement = formulaPlacement(cell.address, cell.col, cell.row, cell.value);
+            if (placement !== undefined)
+                placements.push(placement);
+        }
+    }
+    const { cellsRemoved, formulasRemoved } = arrayRangeRepair(placements);
+    if (cellsRemoved.length === 0 && formulasRemoved.length === 0)
+        return;
+    const mastersRemoved = new Set();
+    for (const { address } of cellsRemoved) {
+        const cell = sheet.getCell(address);
+        if (isFormulaValue(cell.value))
+            mastersRemoved.add(address);
+        cell.value = null;
+    }
+    for (const { address } of formulasRemoved) {
+        const cell = sheet.getCell(address);
+        cell.value = cachedResult(cell.value);
+    }
+    if (mastersRemoved.size === 0)
+        return;
+    for (const { cells } of sheet.rows()) {
+        for (const cell of cells) {
+            const value = cell.value;
+            if (isSharedFormulaValue(value) && mastersRemoved.has(value.sharedFormula)) {
+                cell.value = cachedResult(value);
+            }
+        }
+    }
+}
+export function arrayRangeRepair(placements) {
+    const ordered = [...placements].sort((a, b) => a.row - b.row || a.col - b.col);
+    const keptRanges = [];
+    const kept = new MergeIndex(keptRanges);
+    const cellsRemoved = [];
+    const formulasRemoved = [];
+    for (const placement of ordered) {
+        const { col, row } = placement;
+        if (kept.overlapping({ top: row, left: col, bottom: row, right: col }) !== undefined) {
+            cellsRemoved.push(placement);
+            continue;
+        }
+        const range = placement.arrayRef === undefined
+            ? undefined
+            : tryDecodeAnchoredRange(placement.arrayRef, col, row);
+        if (range === undefined)
+            continue;
+        if (kept.overlapping(range) !== undefined) {
+            formulasRemoved.push(placement);
+            continue;
+        }
+        keptRanges.push(range);
+        kept.note(range);
+    }
+    return { cellsRemoved, formulasRemoved };
+}
+function cachedResult(value) {
+    return typeof value === 'object' &&
+        value !== null &&
+        'result' in value &&
+        value.result !== undefined
+        ? value.result
+        : null;
+}
+export function admitting(build) {
+    try {
+        return build();
+    }
+    catch (error) {
+        if (error instanceof AuthoringError ||
+            error instanceof RangeError ||
+            error instanceof SyntaxError) {
+            return undefined;
+        }
+        throw error;
+    }
+}

package/dist/io/style/cell-style-resolution.d.ts

@@ -0,0 +1,25 @@
+import type { XfStyle } from './xf-style.ts';
+/**
+ * The cell → row → column → xf 0 style resolution for one worksheet, fed in the order every reader
+ * already visits a sheet: column formats before any cell refers to them, a row before its own cells.
+ * Columns are 1-based, and a negative style index means "declares no format".
+ */
+export declare class CellStyleResolver {
+    #private;
+    /** Record the format a span of columns gives its cells. */
+    noteColumnSpan(first: number, last: number, styleIndex: number): void;
+    /**
+     * Open a row. Its format reaches its cells only when the row is marked `customFormat`; without that
+     * flag the format describes the row itself and is not inherited.
+     */
+    openRow(styleIndex: number, customFormat: boolean): void;
+    /** Close the row, so a cell outside one never inherits the last row's format. */
+    closeRow(): void;
+    /**
+     * The style a cell resolves to: its own, else its row's, else its column's, else xf 0. `undefined`
+     * only when the index it resolves to names no record in `xfStyles`, a damaged or truncated table.
+     */
+    styleFor(col: number, cellStyleIndex: number, xfStyles: ReadonlyArray<XfStyle>): XfStyle | undefined;
+    /** Whether the cell, its row or its column declares a format, rather than the cell falling to xf 0. */
+    declaresFormat(col: number, cellStyleIndex: number): boolean;
+}