@shbernal/ts-xlsx 3.1.0 → 3.2.0

package/dist/xml/xml.js

@@ -46,6 +46,12 @@ export function textElement(value) {
     const space = needsSpacePreserve(value) ? ' xml:space="preserve"' : '';
     return `<t${space}>${escapeSpreadsheetText(value)}</t>`;
 }
+export function startTag(name, attrs, selfClosing) {
+    let out = `<${name}`;
+    for (const key in attrs)
+        out += ` ${key}="${escapeAttr(attrs[key] ?? '')}"`;
+    return `${out}${selfClosing ? '/>' : '>'}`;
+}
 export function boolAttr(name, value) {
     return value === undefined ? '' : ` ${name}="${value ? 1 : 0}"`;
 }
@@ -61,6 +67,22 @@ export function checkedToken(value, isValid, kind) {
 export function numAttr(name, value) {
     return value === undefined ? '' : ` ${name}="${numberText(value)}"`;
 }
+export function intAttr(name, value, min = -Number.MAX_SAFE_INTEGER) {
+    if (value === undefined)
+        return '';
+    assertWritableNumber(value);
+    if (!Number.isSafeInteger(value) || value < min) {
+        const floor = min === -Number.MAX_SAFE_INTEGER ? '' : ` of at least ${min}`;
+        throw new AuthoringError(`cannot write ${name}="${value}": expected an integer${floor}`);
+    }
+    return ` ${name}="${value}"`;
+}
+export function nonDefaultNumAttr(name, value, defaultValue) {
+    if (value === undefined)
+        return '';
+    const text = numberText(value);
+    return value === defaultValue ? '' : ` ${name}="${text}"`;
+}
 export function assertWritableDate(date, property) {
     const time = date.getTime();
     if (Number.isNaN(time)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shbernal/ts-xlsx",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "A TypeScript-first library for reading and writing xlsx (OOXML) spreadsheets.",
   "keywords": [
     "csv",
@@ -90,6 +90,7 @@
     "docs:check": "node scripts/gen-docs.ts && git add --intent-to-add -- docs/api && git diff --exit-code -- docs/api",
     "constitution:check": "node scripts/check-constitution.ts",
     "layering:check": "node scripts/check-layering.ts",
+    "corpus-blind:check": "node scripts/check-corpus-blind.ts",
     "entries:check": "node scripts/check-entries.ts",
     "public-types:check": "node scripts/check-public-types.ts",
     "facet-register:check": "node scripts/check-facet-register.ts",
@@ -129,8 +130,8 @@
     "jszip": "^3.10.1",
     "lefthook": "^2.1.12",
     "ooxml-validate": "^0.0.3",
-    "oxfmt": "^0.65.0",
-    "oxlint": "^1.80.0",
+    "oxfmt": "^0.67.0",
+    "oxlint": "^1.82.0",
     "oxlint-tsgolint": "7.0.2001",
     "shiki": "^4.4.3",
     "typescript": "^7.0.2",
@@ -140,5 +141,5 @@
   "engines": {
     "node": ">=24"
   },
-  "packageManager": "pnpm@11.11.0"
+  "packageManager": "pnpm@12.3.4"
 }

package/skills/ts-xlsx-upstream/SKILL.md

@@ -5,7 +5,7 @@ description: Report a ts-xlsx (@shbernal/ts-xlsx) bug, gap, or wrong output to i
 
 # Reporting a ts-xlsx problem upstream
 
-You are in a project that *uses* `@shbernal/ts-xlsx`, not the project that builds it.
+You are in a project that _uses_ `@shbernal/ts-xlsx`, not the project that builds it.
 This skill is how a defect you hit here becomes a permanent regression test there.
 
 The library's maintainers turn reports with a minimal reproduction into corpus cases,
@@ -20,12 +20,12 @@ builds its own input.** Everything below is in service of that.
 Catch the error and read `code` — the taxonomy is deliberately coarse and each answer
 means something different about whose bug it is.
 
-| `error.code`          | Whose bug        | Report it?                                                     |
-| --------------------- | ---------------- | -------------------------------------------------------------- |
-| `internal`            | **ts-xlsx**      | Always. The library says so itself in the message.              |
-| `unsupported-format`  | usually the file | Only if the file opens **cleanly in Excel**. Then it's our gap. |
-| `malformed-input`     | usually the file | Same test: clean in Excel but rejected here means it's ours.    |
-| `authoring`           | usually you      | Only if the document it refused is one Excel can express.       |
+| `error.code`         | Whose bug        | Report it?                                                      |
+| -------------------- | ---------------- | --------------------------------------------------------------- |
+| `internal`           | **ts-xlsx**      | Always. The library says so itself in the message.              |
+| `unsupported-format` | usually the file | Only if the file opens **cleanly in Excel**. Then it's our gap. |
+| `malformed-input`    | usually the file | Same test: clean in Excel but rejected here means it's ours.    |
+| `authoring`          | usually you      | Only if the document it refused is one Excel can express.       |
 
 Not every defect throws. These are ours too, and are worth reporting:
 
@@ -34,7 +34,7 @@ Not every defect throws. These are ours too, and are worth reporting:
 - Types that make correct code fail to compile, or admit code that throws at runtime.
 - Documented behaviour that does not match observed behaviour.
 
-If the problem is that ts-xlsx does not *have* a feature, that is still worth filing —
+If the problem is that ts-xlsx does not _have_ a feature, that is still worth filing —
 as a feature request rather than a bug.
 
 ## 2. Collect the facts
@@ -54,7 +54,7 @@ salaries, customer lists, and unreleased numbers. Treat every file in this repo
 confidential unless the user tells you otherwise, and never upload one to a public
 tracker — including "just a screenshot of the sheet".
 
-Instead, write a self-contained script that *constructs* its input and fails:
+Instead, write a self-contained script that _constructs_ its input and fails:
 
 ```ts
 import {Workbook, writeXlsx, readXlsx} from '@shbernal/ts-xlsx';
@@ -72,13 +72,13 @@ Then cut it down: remove rows, styles, sheets, and options one at a time, re-run
 after each cut, until removing anything more makes the failure disappear. What is left
 is the report.
 
-If the failure only reproduces with a *specific file* you cannot share, do not ask for
+If the failure only reproduces with a _specific file_ you cannot share, do not ask for
 permission to share it — file without the file. Say exactly that in the report and describe
 the structural feature you believe is responsible (a shared formula, a pivot cache, an
 inline string, a particular namespace prefix). A maintainer can usually synthesize a file
 from that description; they can never unsee an attachment.
 
-If you need a file attached, build one: reproduce the *structure* you suspect in a workbook
+If you need a file attached, build one: reproduce the _structure_ you suspect in a workbook
 you generate, with invented values. A synthesized file is always safe to attach. A redacted
 one is not yours to judge — redaction fails quietly, and a public tracker is permanent.
 
@@ -105,7 +105,7 @@ file from this project is attached. When you cannot manage a self-contained repr
 the answer is a thinner report — the prose description from step 3 — not a question and not
 an attachment.
 
-`gh` defaults to the *current* repository — which here is the consumer's, not ts-xlsx's.
+`gh` defaults to the _current_ repository — which here is the consumer's, not ts-xlsx's.
 Always pass `--repo shbernal/ts-xlsx` explicitly, or you will file the bug into the wrong
 tracker.
 
@@ -121,31 +121,39 @@ issue forms, so mirror its sections in the body file so both routes land the sam
 
 ````markdown
 ### ts-xlsx version
+
 <x.y.z>
 
 ### Node version
+
 <vXX.Y.Z>
 
 ### Error code and class
-<code> / <ClassName>   (or: no error thrown — wrong output)
+
+<code> / <ClassName> (or: no error thrown — wrong output)
 
 ### What happened
+
 <observed>
 
 ### What should have happened
+
 <expected, and why you believe that — a spec clause, Excel's own behaviour, or the docs>
 
 ### Minimal reproduction
+
 ```ts
 <the script from step 3>
 ```
 
 ### Error output
+
 ```
 <verbatim message and stack>
 ```
 
 ### Attached file
+
 <none / synthesized — describe how it was generated>
 ````
 

package/dist/core/modern-functions.d.ts

@@ -1 +0,0 @@
-export declare const MODERN_FUNCTIONS: ReadonlySet<string>;

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

@@ -1,25 +0,0 @@
-/** The attributes this resolver reads, the subset both readers' scanners already hand it. */
-interface StyleAttributes {
-    readonly [key: string]: string | undefined;
-}
-/**
- * The cell → row → column style resolution for one worksheet, fed by the same elements in the same
- * order both readers already visit them: `<col>` before any cell references it, `<row>` before its
- * own cells.
- */
-export declare class CellStyleResolver {
-    #private;
-    /** Record a `<col min max style>` span's default for the columns it covers. */
-    noteColumnSpan(first: number, last: number, attrs: StyleAttributes): void;
-    /** Open a `<row>`, taking the format it declares for its own bare cells. */
-    openRow(attrs: StyleAttributes): void;
-    /** Close the row, so a cell outside one never inherits the last row's format. */
-    closeRow(): void;
-    /**
-     * The `xfStyles` index a cell's format resolves to, or `-1` when nothing declares one. A row's
-     * format applies only when the row is marked `customFormat`; without that flag the `s` on a `<row>`
-     * describes the row itself and is not inherited by its cells.
-     */
-    indexFor(col: number, cellStyleIndex: number): number;
-}
-export {};

package/dist/io/xlsx/cell-style-resolution.js

@@ -1,29 +0,0 @@
-import { numInteger } from '../../xml/xml-attrs.js';
-import { boolStrict } from '../../xml/xml-scan.js';
-export class CellStyleResolver {
-    #columnStyle = new Map();
-    #rowStyle = -1;
-    #rowCustomFormat = false;
-    noteColumnSpan(first, last, attrs) {
-        const styleIndex = numInteger(attrs.style, 0) ?? -1;
-        if (styleIndex < 0)
-            return;
-        for (let index = first; index <= last; index++)
-            this.#columnStyle.set(index, styleIndex);
-    }
-    openRow(attrs) {
-        this.#rowStyle = numInteger(attrs.s, 0) ?? -1;
-        this.#rowCustomFormat = boolStrict(attrs.customFormat);
-    }
-    closeRow() {
-        this.#rowStyle = -1;
-        this.#rowCustomFormat = false;
-    }
-    indexFor(col, cellStyleIndex) {
-        if (cellStyleIndex >= 0)
-            return cellStyleIndex;
-        if (this.#rowCustomFormat && this.#rowStyle >= 0)
-            return this.#rowStyle;
-        return this.#columnStyle.get(col) ?? -1;
-    }
-}

package/dist/io/xlsx/column-budget.d.ts

@@ -1,26 +0,0 @@
-import { type XmlAttributes } from '../../xml/xml-scan.ts';
-/**
- * A per-sheet allowance of column touches, spent by each `<col>` span the reader applies.
- *
- * A span past the allowance is truncated, and one starting past it is dropped, rather than the read
- * being refused: that is the stance both readers already take on an out-of-grid span, 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 a `<col min max>` element actually applies to, or `undefined` for one that applies to
- * none: unreadable bounds, a span starting past the grid, or a budget already spent.
- *
- * Beside the budget because the two decisions are one decision. Both readers had their own copy, and
- * the copies had already drifted: one tested `min > MAX_COLUMN` and the other did not, which happened
- * not to matter only because `budget.take` returns `undefined` when `first > last` - an accident of
- * this class's contract rather than an agreement between the readers.
- */
-export declare function takeColumnSpan(attrs: XmlAttributes, budget: ColumnRecordBudget): {
-    first: number;
-    last: number;
-} | undefined;

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

@@ -1,26 +0,0 @@
-/**
- * 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;
-/**
- * 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/xlsx/read-repair.js

@@ -1,39 +0,0 @@
-import { INVALID_SHEET_NAME_CHARS, MAX_SHEET_NAME_LENGTH } from '../../core/limits.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);
-}
-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 admitting(build) {
-    try {
-        return build();
-    }
-    catch (error) {
-        if (error instanceof AuthoringError ||
-            error instanceof RangeError ||
-            error instanceof SyntaxError) {
-            return undefined;
-        }
-        throw error;
-    }
-}