@shbernal/ts-xlsx 1.0.3 → 1.2.0

package/dist/customui/errors.js

@@ -1,14 +1,4 @@
 import { XlsxError } from '../errors.js';
-/**
- * Thrown when a `customUI` ribbon-customisation part (`customUI/customUI.xml` or
- * `customUI/customUI14.xml`) is present but cannot be parsed into a {@link CustomUiDocument} — malformed
- * XML, a missing or unrecognised `<customUI>` root namespace, or nesting deep enough to look hostile.
- * A workbook with no ribbon customisation never produces this: {@link Workbook.customUI} is an empty
- * array instead.
- *
- * The parser treats the part as hostile input (a spreadsheet library parses untrusted files), so a
- * malformed structure fails closed with this error rather than yielding a half-built tree.
- */
 export class CustomUiParseError extends XlsxError {
     name = 'CustomUiParseError';
     code = 'malformed-input';

package/dist/customui/index.js

@@ -1,7 +1,2 @@
-// Native `customUI` ribbon read: project a typed, read-only view of the ribbon tree (tabs → groups →
-// controls + callback names) over the `customUI.xml` / `customUI14.xml` parts a macro workbook carries.
-// Those parts are preserved byte-for-byte on round-trip (see `src/core/preserved.ts`); this is a
-// projection over them, the same posture as the VBA read view (`src/vba`). Authoring/editing the ribbon
-// is out of scope — round-trip fidelity already comes from verbatim preservation.
 export { CustomUiParseError } from './errors.js';
 export { CUSTOMUI_2006_NAMESPACE, CUSTOMUI_2007_REL_TYPE, CUSTOMUI_2009_NAMESPACE, CUSTOMUI_2010_REL_TYPE, isCustomUiRelType, parseCustomUi, } from './ribbon.js';

package/dist/customui/ribbon.js

@@ -1,40 +1,13 @@
-// Turn a `customUI` ribbon-customisation part into a typed, read-only view of the ribbon tree.
-//
-// A `.xlsm` can carry two ribbon parts hung off the *package root* rels: `customUI/customUI.xml`
-// (Office 2007 RibbonX, namespace `.../2006/01/customui`) and `customUI/customUI14.xml` (Office 2010+,
-// namespace `.../2009/07/customui`, which adds backstage/QAT/commands). Both are preserved verbatim on
-// round-trip (see `src/core/preserved.ts`); this module adds a reader on top, mirroring how
-// `parseVbaProject` projects a read view over bytes the writer already round-trips opaquely.
-//
-// Scope (v1): the `<ribbon>` subtree only — tabs → groups → controls, plus each control's callback
-// names (the `onAction` a click invokes is the whole reason a macro workbook ships a ribbon). A
-// customUI document's `<commands>`, `<backstage>`, `<contextMenus>`, and the ribbon's `qat`/
-// `contextualTabs` are NOT parsed; they still round-trip byte-for-byte, they are just not surfaced here.
-//
-// Security posture: the part is untrusted input. The underlying `xmlEvents` scanner never expands
-// entities or DTDs (see `xml-read.ts`); on top of that this parser caps nesting depth and fails closed
-// with {@link CustomUiParseError} on any malformed or unrecognised structure rather than returning a
-// half-built tree.
 import { strFromU8 } from 'fflate';
 import { boolStrict, localName, xmlEvents } from '../xml/xml-read.js';
 import { CustomUiParseError } from './errors.js';
-/** The `customUI` root namespaces, one per {@link RibbonDialect}. */
 export const CUSTOMUI_2006_NAMESPACE = 'http://schemas.microsoft.com/office/2006/01/customui';
 export const CUSTOMUI_2009_NAMESPACE = 'http://schemas.microsoft.com/office/2009/07/customui';
-// The OPC relationship Type URIs Office wires the two ribbon parts under, from the package-root rels.
-// Both end `/ui/extensibility` (the 2010 one confusingly carries `2007` in its path); the reader
-// matches on that suffix — {@link isCustomUiRelType} — exactly as the rest of the reader matches
-// preserved relationship types by local suffix.
 export const CUSTOMUI_2007_REL_TYPE = 'http://schemas.microsoft.com/office/2006/relationships/ui/extensibility';
 export const CUSTOMUI_2010_REL_TYPE = 'http://schemas.microsoft.com/office/2007/relationships/ui/extensibility';
-/** Whether a package-root relationship Type URI points at a `customUI` ribbon part. */
 export function isCustomUiRelType(type) {
     return type.endsWith('/ui/extensibility');
 }
-// A hostile part could nest elements thousands deep; the recursive control mapper would then overflow
-// the call stack with an uncatchable RangeError. Capping tree depth keeps every failure a
-// CustomUiParseError. Real ribbons nest only a handful deep (tab > group > menu > submenu), so this
-// bound is unreachable by any legitimate document.
 const MAX_DEPTH = 256;
 const KNOWN_KINDS = new Set([
     'button',
@@ -56,12 +29,6 @@ const KNOWN_KINDS = new Set([
     'control',
     'item',
 ]);
-/**
- * Parse a `customUI` part (raw UTF-8 bytes or its decoded text) into a {@link CustomUiDocument}.
- *
- * @throws {CustomUiParseError} if the XML is malformed, the root is not a `<customUI>` element in
- *   a recognised namespace, or the tree nests beyond {@link MAX_DEPTH}.
- */
 export function parseCustomUi(input) {
     const xml = typeof input === 'string' ? input : strFromU8(input);
     let root;
@@ -82,10 +49,6 @@ export function parseCustomUi(input) {
     const ribbonEl = findChild(customUi, 'ribbon');
     return ribbonEl === undefined ? { dialect } : { dialect, ribbon: toRibbon(ribbonEl) };
 }
-// Resolve the namespace bound to the customUI element's own name and map it to a dialect. A default
-// namespace (`xmlns=`) governs an unprefixed `<customUI>`; a prefixed `<p:customUI>` is governed by
-// that prefix's `xmlns:p`. Neither of the two known namespaces present means this is not a customUI part
-// this reader understands — fail closed rather than guess.
 function dialectOf(customUi) {
     const colon = customUi.name.indexOf(':');
     const nsAttr = colon === -1 ? 'xmlns' : `xmlns:${customUi.name.slice(0, colon)}`;
@@ -127,8 +90,6 @@ function toControl(el) {
         ...(el.children.length > 0 ? { children: el.children.map((child) => toControl(child)) } : {}),
     };
 }
-// The id/label attributes lifted onto every tab, group, and control. Emitted only when present, so an
-// absent attribute stays absent (exactOptionalPropertyTypes) rather than becoming an explicit undefined.
 function identity(attrs) {
     return {
         ...(attrs.id !== undefined ? { id: attrs.id } : {}),
@@ -137,10 +98,6 @@ function identity(attrs) {
         ...(attrs.label !== undefined ? { label: attrs.label } : {}),
     };
 }
-// Build the element tree from the SAX event stream with an explicit stack (no recursion), capping depth
-// so a hostile part cannot force the later recursive walk to overflow. Text and comments carry no ribbon
-// meaning and are ignored. Throws CustomUiParseError on unbalanced markup; a lower-level SyntaxError from
-// the scanner is caught and re-wrapped by the caller.
 function buildTree(xml) {
     const root = { name: '#root', local: '#root', attrs: {}, children: [] };
     const stack = [root];

package/dist/entries/core.d.ts

@@ -7,6 +7,7 @@ export type { Comment, CommentThread, Mention, Person } from '../core/comment-th
 export type { CfValueObject, ConditionalFormatting, ConditionalFormattingRule, } from '../core/conditional-formatting.ts';
 export type { DataValidation, DataValidationEntry, DataValidationErrorStyle, DataValidationOperator, DataValidationType, } from '../core/data-validation.ts';
 export { type AnchoredImage, type AnchorPoint, type Extent, type ImageAnchor, type ImageEditAs, isOneCellAnchor, type OneCellAnchor, PX_TO_EMU, type TwoCellAnchor, type WorkbookImage, } from '../core/image.ts';
+export { MAX_COLUMN_WIDTH, MAX_ROW_HEIGHT } from '../core/limits.ts';
 export type { HeaderFooter, PageBreak, PageMargins, PageSetup, PrintOptions, } from '../core/page-setup.ts';
 export { type ParsedPivotField, type ParsedPivotSource, type ParsedPivotTable, type PivotCacheField, type PivotItem, type PivotMetric, type PivotNumericSummary, type PivotRecordCell, type PivotSourceKind, PivotTable, type PivotTableOptions, } from '../core/pivot-table.ts';
 export type { PreservedPart, PreservedRelationship, PreservedRootReference, PreservedWorksheetReference, } from '../core/preserved.ts';
@@ -16,8 +17,9 @@ export { Row } from '../core/row.ts';
 export type { Alignment, Border, BorderEdge, BorderStyle, CellStyle, Color, DifferentialStyle, Fill, FillPatternType, Font, FontScheme, FontVerticalAlignment, GradientFill, GradientStop, HorizontalAlignment, NamedCellStyle, PatternFill, Protection, TableStyleNamespace, TableStyleTable, UnderlineStyle, VerticalAlignment, } from '../core/style.ts';
 export { Table, type TableColumn, type TableColumnStyle, type TableOptions, type TableRegion, type TableStyleInfo, } from '../core/table.ts';
 export { isTableStyleElementType, STRIPE_ELEMENT_TYPES, TABLE_STYLE_ELEMENT_TYPES, type TableStyle, type TableStyleElement, type TableStyleElementType, } from '../core/table-style.ts';
+export { estimateWrappedLines } from '../core/text-metrics.ts';
 export { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, parseThemeColorScheme, THEME_COLOR_SLOTS, type ThemeColorScheme, type ThemeColorSlot, type ThemeFontScheme, type ThemeOverrides, } from '../core/theme.ts';
-export { type CellValue, coerceCellValue, type DataTableFormulaValue, detectValueType, ERROR_CODES, type ErrorCode, type ErrorValue, type FormulaResult, type FormulaValue, type HyperlinkValue, isErrorCode, type RichTextRun, type RichTextValue, richTextToPlain, type SharedFormulaValue, ValueType, } from '../core/value.ts';
+export { type CellValue, cellValueToText, coerceCellValue, type DataTableFormulaValue, detectValueType, ERROR_CODES, type ErrorCode, type ErrorValue, type FormulaResult, type FormulaValue, type HyperlinkValue, isDataTableFormulaValue, isErrorCode, isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, type RichTextRun, type RichTextValue, richTextToPlain, type SharedFormulaValue, ValueType, } from '../core/value.ts';
 export { type AddImageOptions, type AddWorksheetOptions, DEFAULT_WORKBOOK_VIEW, type DefinedName, type PreservedWorkbookReference, Workbook, type WorkbookProperties, type WorkbookView, } from '../core/workbook.ts';
 export type { WorkbookProtection, WorkbookProtectionCredentialAttr, } from '../core/workbook-protection.ts';
 export { type CellModel, type ColumnProperties, type OutlineProperties, type RowInput, type RowProperties, type SheetView, Worksheet, type WorksheetModel, type WorksheetProperties, type WorksheetState, } from '../core/worksheet.ts';

package/dist/entries/core.js

@@ -1,20 +1,16 @@
-// Entry barrel for `@shbernal/ts-xlsx/core` — the document model, with no serialisation attached.
-//
-// This is what a consumer imports to build or inspect a workbook in memory: the classes, the
-// property shapes, and the value vocabulary. It pulls in no ZIP, no XML writer and no BIFF12
-// decoder. Errors are not here — the whole failure taxonomy lives behind `/errors`, so that a
-// caller who only needs to branch on a failure never loads a codec to get the class.
 export { columnToNumber, decodeAddress, decodeRange, encodeAddress, MAX_COLUMN, MAX_ROW, numberToColumn, } from '../core/address.js';
 export { Cell } from '../core/cell.js';
 export { applyTint, DEFAULT_INDEXED_COLORS, resolveColor, SYSTEM_INDEXED_COLORS, } from '../core/color-resolution.js';
 export { Column } from '../core/column.js';
 export { isOneCellAnchor, PX_TO_EMU, } from '../core/image.js';
+export { MAX_COLUMN_WIDTH, MAX_ROW_HEIGHT } from '../core/limits.js';
 export { PivotTable, } from '../core/pivot-table.js';
 export { Range } from '../core/range.js';
 export { Row } from '../core/row.js';
 export { Table, } from '../core/table.js';
 export { isTableStyleElementType, STRIPE_ELEMENT_TYPES, TABLE_STYLE_ELEMENT_TYPES, } from '../core/table-style.js';
+export { estimateWrappedLines } from '../core/text-metrics.js';
 export { DEFAULT_THEME_COLOR_SCHEME, DEFAULT_THEME_FONTS, parseThemeColorScheme, THEME_COLOR_SLOTS, } from '../core/theme.js';
-export { coerceCellValue, detectValueType, ERROR_CODES, isErrorCode, richTextToPlain, ValueType, } from '../core/value.js';
+export { cellValueToText, coerceCellValue, detectValueType, ERROR_CODES, isDataTableFormulaValue, isErrorCode, isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, ValueType, } from '../core/value.js';
 export { DEFAULT_WORKBOOK_VIEW, Workbook, } from '../core/workbook.js';
 export { Worksheet, } from '../core/worksheet.js';

package/dist/entries/csv.js

@@ -1,6 +1,2 @@
-// Entry barrel for `@shbernal/ts-xlsx/csv` — delimited text in and out.
-//
-// The two directions are asymmetric in what they cost: writing needs only a worksheet and the
-// value vocabulary, while reading builds a `Workbook` and therefore pulls the model in whole.
 export { readCsv } from '../io/csv/read.js';
 export { writeCsv, writeCsvText } from '../io/csv/write.js';

package/dist/entries/customui.js

@@ -1,3 +1 @@
-// Entry barrel for `@shbernal/ts-xlsx/customui` — the read-only ribbon view over a macro
-// workbook's preserved `customUI` parts.
 export { CUSTOMUI_2006_NAMESPACE, CUSTOMUI_2007_REL_TYPE, CUSTOMUI_2009_NAMESPACE, CUSTOMUI_2010_REL_TYPE, isCustomUiRelType, parseCustomUi, } from '../customui/ribbon.js';

package/dist/entries/errors.js

@@ -1,16 +1,3 @@
-// Entry barrel for `@shbernal/ts-xlsx/errors` — the whole failure taxonomy, and nothing else.
-//
-// Every error class the library throws is exported here and from no other entry. That rule is
-// what keeps the entry barrels disjoint (a container-level failure belongs to no single codec:
-// `readXlsx` and `readXlsb` both raise `UnsupportedFormatError`), and it makes the answer to
-// "what can this throw at me?" one import rather than a hunt across codecs.
-//
-// It is also the cheapest thing in the package by an order of magnitude: the classes reach
-// nothing but each other, so a service that only needs to classify a failure — log it, map it to
-// an HTTP status, decide whether to retry — pays for the taxonomy and not for a parser.
-//
-// `XlsxError` is the one-line answer to "was that us?"; `XlsxErrorCode` is the kind of failure,
-// shared across classes on purpose (see `src/errors.ts`).
 export { CustomUiParseError } from '../customui/errors.js';
 export { AuthoringError, InternalError, XlsxError } from '../errors.js';
 export { PackageReadError, UnsupportedFormatError, } from '../io/opc/errors.js';

package/dist/entries/vba.js

@@ -1,7 +1,2 @@
-// Entry barrel for `@shbernal/ts-xlsx/vba` — the native VBA read view and the structural edits.
-//
-// A deliberately narrower face than `src/vba/index.ts`, which is the *internal* barrel and also
-// carries the CFB writer, the MS-OVBA container primitives and the part-path constants that
-// `Workbook` and the codecs need. Those are implementation, not API.
 export { parseVbaProject, } from '../vba/project.js';
 export { addVbaReference, removeVbaModule, } from '../vba/project-editor.js';

package/dist/entries/xlsb.js

@@ -1,7 +1 @@
-// Entry barrel for `@shbernal/ts-xlsx/xlsb` — the BIFF12 reader.
-//
-// `readXlsx` auto-detects and reads a binary `.xlsb` too, so most callers never name this; it is
-// public for the caller that holds bytes it already knows to be `.xlsb` and wants to say so. That
-// dispatch also means this entry is not the way to *avoid* the BIFF12 codec — importing
-// `/xlsx` loads it either way (see the per-entry budgets in `scripts/size-budget.ts`).
 export { readXlsb } from '../io/xlsb/read.js';

package/dist/entries/xlsx.js

@@ -1,16 +1,3 @@
-// Entry barrel for `@shbernal/ts-xlsx/xlsx` — the XML codec: whole-workbook read and write, the
-// streaming pair, and the in-place VBA part edits.
-//
-// The streaming reader's entry points are public; the granular per-row/cell/sheet output shapes
-// (`StreamedRow`/`StreamedCell`/`StreamedSheet` as *read*) are intentionally left as inferred
-// structural types rather than named commitments while that surface settles. The streaming
-// *writer*'s whole surface is named: its incremental workbook/worksheet/row handles are classes
-// and their options are interfaces, so there is nothing structural left un-named. A styled row
-// hands back `Cell`, which belongs to `/core`.
-//
-// Streaming is not its own entry point. Measured, `read-rows` + `write-stream` reach every module
-// `read` + `write` do plus three — an entry that costs what the codec costs is an alias, not a
-// packaging boundary.
 export { editXlsxVbaAddReference, editXlsxVbaRemoveModule } from '../io/xlsx/edit-vba.js';
 export { readXlsx } from '../io/xlsx/read.js';
 export { readSheetRows, readWorkbookStream, } from '../io/xlsx/read-rows.js';

package/dist/errors.d.ts

@@ -14,6 +14,12 @@
  * unreachable exhaustiveness guard (so: `'internal'`), and the one genuine feature gap — a binary
  * `.xlsb` cannot be row-streamed — is already reported by {@link UnsupportedFormatError}'s `format`
  * branch. A code with no throw site would be a promise the library does not keep.
+ *
+ * **Which of these is worth reporting upstream.** `'internal'` always is, and says so at runtime.
+ * `'unsupported-format'` and `'malformed-input'` are worth reporting when the file in hand opens
+ * cleanly in Excel — that combination means we are the ones who cannot read it, which is a gap, not
+ * a corrupt input. `'authoring'` is worth reporting only if the document it refused is one a real
+ * workbook can express. See `skills/ts-xlsx-upstream` for how to file one.
  */
 export type XlsxErrorCode = 'unsupported-format' | 'malformed-input' | 'authoring' | 'internal';
 /**
@@ -58,8 +64,16 @@ export declare class AuthoringError extends XlsxError {
  * No caller can provoke one, so it is not a failure mode to handle: seeing it means the bug is ours.
  * It exists as a distinct type so that "unreachable" is *stated* rather than implied by a bare
  * `Error`, which reads identically to a throw nobody has classified yet.
+ *
+ * It is the one class in the taxonomy that rewrites its own message, appending {@link REPORT_NOTICE}
+ * below the invariant that broke. The constructor is where that lives so a throw site added later
+ * inherits it — the alternative, a notice pasted at each of the throw sites, is one every future
+ * site can forget. Every other class leaves `message` exactly as given: `'malformed-input'` is a
+ * routine outcome for a library that reads untrusted files, and a "report this" banner on each
+ * corrupt input would train callers to ignore the one banner that always means something.
  */
 export declare class InternalError extends XlsxError {
     readonly name = "InternalError";
     readonly code = "internal";
+    constructor(message?: string, options?: ErrorOptions);
 }

package/dist/errors.js

@@ -1,66 +1,15 @@
-// The failure taxonomy every layer throws through.
-//
-// Typed error classes grew up one per subsystem that happened to want one, sharing no ancestor, so a
-// caller could not ask "did *this library* fail?" without naming all of them — while the model's own
-// validation threw bare `Error`, distinguishable only by string-matching the message. For a library
-// whose input is untrusted files, "was it my file or my call?" is a first-class question, and it had
-// no answer.
-//
-// Two levels of branch, deliberately non-redundant:
-//   - `code` says what *kind* of failure this is — the question a caller usually has.
-//   - `name` (and `instanceof`) says exactly which one — the question a caller occasionally has.
-// A code shared by several classes is the design, not an oversight: a `code` in 1:1 correspondence
-// with the classes would carry nothing the class did not already carry.
-//
-// Scalar argument validation stays *outside* this taxonomy — see {@link AuthoringError} for where the
-// line falls and why.
-//
-// This module sits below every layer that throws (`src/xml`, `src/core`, `src/io`, `src/vba`,
-// `src/customui` all import it), so it imports nothing itself; `scripts/check-layering.ts` enforces
-// that.
-/**
- * The common ancestor of every error this library raises deliberately. `catch (e) { if (e instanceof
- * XlsxError) … }` is the one-line answer to "was that us?", and {@link code} then says which kind of
- * failure it was without naming a single subclass.
- *
- * Abstract on purpose: a failure always has a kind, so there is never a reason to throw the base.
- * Every subclass fixes {@link code} to a literal, which makes the class hierarchy a discriminated
- * union — narrowing on `error.code` narrows the type.
- *
- * The constructor is inherited from `Error`, so every subclass accepts `{cause}`; layers that wrap a
- * lower-level failure are expected to pass it rather than flatten it into the message.
- */
 export class XlsxError extends Error {
 }
-/**
- * Thrown when the caller describes a document that cannot exist: a pivot table with no row field, a
- * table whose columns do not span its range, a merge that overlaps another, a workbook with no
- * worksheets. The document model, not a single argument, is what is wrong.
- *
- * **Where the line falls against native errors.** A single scalar that is out of range, unparseable,
- * or the wrong type stays a native `RangeError` / `SyntaxError` / `TypeError` — those types exist for
- * exactly that, every caller already reads them, and wrapping them would make this taxonomy a
- * re-implementation of the language's. `AuthoringError` starts where a *composite* is internally
- * inconsistent, or contradicts something a workbook can express. `getColumn(0)` is a `RangeError`;
- * a table that names a column twice is an `AuthoringError`.
- *
- * It is always the calling code that is wrong, never the input file — a malformed file raises a
- * `'malformed-input'` error instead.
- */
 export class AuthoringError extends XlsxError {
     name = 'AuthoringError';
     code = 'authoring';
 }
-/**
- * Thrown where an invariant the library itself maintains turns out not to hold — typically an index
- * that a preceding pass proved to be in range, re-checked because `noUncheckedIndexedAccess` makes
- * the possibility of `undefined` explicit and casting it away would be worse.
- *
- * No caller can provoke one, so it is not a failure mode to handle: seeing it means the bug is ours.
- * It exists as a distinct type so that "unreachable" is *stated* rather than implied by a bare
- * `Error`, which reads identically to a throw nobody has classified yet.
- */
+const REPORT_NOTICE = 'This is a bug in ts-xlsx, not in your file or your code. Please report it:\n' +
+    'https://github.com/shbernal/ts-xlsx/issues/new?template=agent-report.yml&labels=agent-reported';
 export class InternalError extends XlsxError {
     name = 'InternalError';
     code = 'internal';
+    constructor(message, options) {
+        super(message === undefined ? REPORT_NOTICE : `${message}\n\n${REPORT_NOTICE}`, options);
+    }
 }

package/dist/index.js

@@ -1,15 +1,3 @@
-// The convenience entry point: everything the package exports, under one specifier.
-//
-// It is a union of the subpath entry barrels in `src/entries/`, which are the real public faces —
-// `@shbernal/ts-xlsx/core`, `/xlsx`, `/xlsb`, `/csv`, `/vba`, `/customui`, `/errors`. Each symbol
-// is listed in exactly one of them, so there is no second list to keep in step here and a star
-// re-export cannot silently drop a name to an ambiguity. `scripts/check-layering.ts` holds the
-// entries disjoint and keeps this file's composition honest.
-//
-// Importing from here is the right default; it costs nothing extra to a bundler, because
-// `sideEffects: false` lets an unused module be dropped whole. Reach for a subpath when the
-// consumer has no bundler to do that for it, or when you want the module graph itself to say
-// which half of the library a service depends on.
 export * from './entries/core.js';
 export * from './entries/csv.js';
 export * from './entries/customui.js';

package/dist/io/csv/read.js

@@ -1,19 +1,5 @@
-// CSV parsing — flat delimited text back into a one-sheet workbook.
-//
-// The hard part of reading CSV is not splitting fields; it is deciding a field's *type* without
-// corrupting data. The rules here are deliberate and lossless-by-default:
-//   - An empty field is the empty cell (`null`); a whitespace-only field is a string, never the
-//     number 0 that `Number("   ")` would silently produce.
-//   - A numeric-looking field becomes a number only when its magnitude is exactly representable
-//     (within the safe-integer range); an oversized id like a 20-digit account number is kept as
-//     its original string so no digits are lost.
-//   - Only a strictly-formatted ISO date (`YYYY-MM-DD`, optional time) becomes a Date; padded ids
-//     and dash-codes such as `2020-00001` or `1-3` stay strings.
-// A caller can override coercion wholesale with `map` (e.g. the identity function to keep every
-// field a raw string, preserving leading zeros).
 import { Workbook } from '../../core/workbook.js';
 import { AuthoringError } from '../../errors.js';
-/** Parse CSV text (or UTF-8 bytes) into a workbook holding a single worksheet. */
 export function readCsv(input, options = {}) {
     const text = stripBom(typeof input === 'string' ? input : Buffer.from(input).toString('utf8'));
     const delimiter = options.delimiter ?? ',';
@@ -32,9 +18,6 @@ export function readCsv(input, options = {}) {
 function stripBom(text) {
     return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
 }
-// A character-scan parser: quotes toggle literal mode, a doubled quote inside a quoted field is one
-// quote, and a row ends on LF (a preceding CR is dropped, so CRLF and LF read the same). A final
-// trailing newline does not yield a spurious empty row.
 function parseCsvRows(text, delimiter) {
     const rows = [];
     let row = [];
@@ -87,7 +70,6 @@ function defaultCsvCoerce(field) {
         return null;
     if (NUMERIC.test(field)) {
         const value = Number(field);
-        // Beyond the safe-integer range a double silently loses digits; keep the original text instead.
         return Number.isFinite(value) && Math.abs(value) <= Number.MAX_SAFE_INTEGER ? value : field;
     }
     const iso = ISO_DATE.exec(field);

package/dist/io/csv/write.js

@@ -1,18 +1,6 @@
-// CSV serialization — the flat-text sibling of the XLSX writer.
-//
-// A worksheet is a rectangle of typed cells; CSV is that rectangle flattened to delimited
-// text. The lossy direction (styles, formulas-as-formulas, multiple sheets) is inherent to the
-// format, so this writer makes the honest choices explicit: one selected sheet, each row sized to
-// its own populated extent (never clamped to a sibling row's width), a formula rendered as its
-// cached result, a Date rendered by a caller-supplied format or a full ISO-8601 timestamp.
-//
-// `writeCsvText` yields the logical text; `writeCsv` encodes it to bytes and — for UTF-8, the
-// default — prepends a byte-order mark so a consumer such as Excel detects the encoding and does
-// not mangle non-ASCII on open. The BOM is a byte-level marker, not part of the logical text.
-import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from '../../core/value.js';
+import { cellValueToText, isDataTableFormulaValue, isFormulaValue, isSharedFormulaValue, } from '../../core/value.js';
 import { AuthoringError } from '../../errors.js';
 const UTF8_BOM = Uint8Array.of(0xef, 0xbb, 0xbf);
-/** The logical CSV text of one worksheet — no BOM, no byte encoding. */
 export function writeCsvText(workbook, options = {}) {
     const sheet = selectSheet(workbook, options.sheetName);
     const delimiter = options.delimiter ?? ',';
@@ -36,7 +24,6 @@ export function writeCsvText(workbook, options = {}) {
     }
     return lines.join(rowDelimiter);
 }
-/** The CSV bytes of one worksheet in the requested encoding, with a UTF-8 BOM by default. */
 export function writeCsv(workbook, options = {}) {
     const text = writeCsvText(workbook, options);
     const encoding = options.encoding ?? 'utf8';
@@ -56,33 +43,16 @@ function selectSheet(workbook, name) {
             throw new AuthoringError('workbook has no worksheet to write as CSV');
         return first;
     }
-    const sheet = workbook.getWorksheet(name);
-    if (sheet === undefined)
-        throw new AuthoringError(`no worksheet named "${name}" to write as CSV`);
-    return sheet;
+    return workbook.requireWorksheet(name);
 }
 function csvFieldText(value, options) {
-    if (value === null)
-        return '';
-    if (typeof value === 'number')
-        return String(value);
-    if (typeof value === 'boolean')
-        return value ? 'TRUE' : 'FALSE';
-    if (typeof value === 'string')
-        return value;
-    if (value instanceof Date)
+    if (value instanceof Date && options.dateFormat !== undefined) {
         return formatDate(value, options.dateFormat, options.dateUTC ?? false);
-    if (isErrorValue(value))
-        return value.error;
-    if (isRichTextValue(value))
-        return richTextToPlain(value);
-    if (isHyperlinkValue(value)) {
-        return typeof value.text === 'string' ? value.text : richTextToPlain(value.text);
     }
-    if (isFormulaValue(value) || isSharedFormulaValue(value)) {
+    if (isFormulaValue(value) || isSharedFormulaValue(value) || isDataTableFormulaValue(value)) {
         return value.result === undefined ? '' : csvFieldText(value.result, options);
     }
-    return '';
+    return cellValueToText(value);
 }
 const DATE_TOKENS = /YYYY|YY|MM|DD|HH|mm|ss|M|D|H|m|s/g;
 function formatDate(date, format, utc) {

package/dist/io/opc/errors.js

@@ -1,25 +1,9 @@
-// Typed errors the reader raises when it is handed something that is not a readable OOXML `.xlsx`
-// package. A spreadsheet library parses untrusted files, so the failure a caller sees must be a clear,
-// programmatically-branchable signal — not a raw zip-internals string (which is opaque, and can leak an
-// absolute filesystem path from the layer below). See the spec
-// `docs/knowledge/specs/unsupported-input-format-typed-error.md`.
 import { XlsxError } from '../../errors.js';
 const DEFAULT_MESSAGE = {
     xls: 'the legacy .xls binary format (BIFF/OLE2 compound file) is not supported; only OOXML .xlsx is read',
     xlsb: 'this entry point does not read the binary .xlsb format (BIFF12)',
     unknown: 'not a valid .xlsx package: no OOXML workbook part was found',
 };
-/**
- * Thrown when input is not a readable `.xlsx` package. The single {@link format} field is the branch a
- * caller keys on (rather than a subclass per format), so a `catch` can distinguish a legacy `.xls`, a
- * binary `.xlsb`, and an unrecognised blob without string-matching the message.
- *
- * The message never carries a filesystem path or the underlying zip library's internals — the whole
- * point of the type is that the classification, not a leaked lower-layer string, is what the caller sees.
- *
- * {@link format} stays the branch for *which* unsupported input this was; the inherited
- * {@link XlsxError.code} answers the coarser question of what kind of failure it is.
- */
 export class UnsupportedFormatError extends XlsxError {
     name = 'UnsupportedFormatError';
     code = 'unsupported-format';
@@ -29,20 +13,6 @@ export class UnsupportedFormatError extends XlsxError {
         this.format = format;
     }
 }
-/**
- * Thrown when the input *is* a ZIP container but it cannot be unpacked: the archive is corrupt or
- * truncated, or inflating it would push total uncompressed output past the caller's bound (which is
- * how a zip bomb presents).
- *
- * The neighbouring {@link UnsupportedFormatError} says the input is a different *kind* of thing; this
- * one says it is the right kind and we will not (or cannot) unpack it. Keeping them apart is what
- * lets a caller answer "should I try another reader, or reject this file?" — and it is what replaced
- * the message-prefix match the bomb refusal used to be recognised by.
- *
- * The zip library's own failure text never survives into either the message or `cause`: it can name
- * internals — or an absolute filesystem path — from the layer below, and this type carries the
- * classification precisely so no lower-layer string has to.
- */
 export class PackageReadError extends XlsxError {
     name = 'PackageReadError';
     code = 'malformed-input';

package/dist/io/opc/inflate.js

@@ -1,38 +1,6 @@
-// Bounded, streaming inflation of an OPC (`.xlsx`) zip package.
-//
-// Decompression is the reader's first hostile-input surface: a "zip bomb" ships a few
-// kilobytes that inflate to gigabytes. The zip's own size headers cannot be trusted to
-// bound this — they are attacker-controlled. A header that declares a *large* size makes a
-// naïve reader preallocate that much (an amplifier: tiny input, huge allocation); a header
-// that lies *small* makes a size-preallocating inflater silently truncate real data. So we
-// consult the declared sizes for nothing. Instead the compressed archive is fed to fflate's
-// streaming unzip in slices, the decompressor grows its output from the bytes it actually
-// produces, and a running counter of real output aborts the moment it crosses the cap.
-//
-// Because DEFLATE cannot expand input by more than ~1032:1, feeding at most INPUT_SLICE
-// compressed bytes before each counter check bounds the worst-case overshoot past the cap
-// to one slice's expansion — not the whole (possibly enormous) stream.
 import { Unzip, UnzipInflate } from 'fflate';
 import { PackageReadError } from './errors.js';
-// Compressed input is pushed in slices this size so decompressed output arrives in
-// increments the running counter can check. Small enough that the worst-case overshoot
-// (slice × DEFLATE's ~1032:1 ceiling ≈ 16 MiB) is negligible against a sane cap; large
-// enough that a legitimate multi-hundred-megabyte package still streams in cheaply.
 const INPUT_SLICE = 1 << 14;
-/**
- * Inflate every part of an `.xlsx` zip package, enforcing a hard ceiling on total
- * decompressed output.
- *
- * @param data The raw zip bytes.
- * @param cap  Maximum total uncompressed output, in bytes, across all parts. Enforced
- *   against bytes actually produced, never against the archive's declared sizes.
- * @returns A map of part path to inflated bytes.
- * @throws {PackageReadError} if inflation would exceed `cap` — a probable zip bomb.
- * @throws {Error} raised by the zip layer if the archive is malformed or a part uses an unsupported
- *   compression method. Callers reach this through {@link inflateSpreadsheetPackage}, which is where
- *   those are classified; the raw error is deliberately not re-typed here, because its text is the
- *   one thing that must not reach a caller unfiltered.
- */
 export function inflatePackage(data, cap) {
     const files = {};
     let total = 0;
@@ -57,9 +25,6 @@ export function inflatePackage(data, cap) {
             if (final)
                 files[file.name] = join(chunks, size);
         };
-        // `start()` reports an unsupported compression method through `ondata` above, then
-        // throws trying to build the missing decoder. Keep the reported error (its message
-        // names the method) and swallow the raw follow-on throw.
         try {
             file.start();
         }

package/dist/io/opc/namespaces.js

@@ -1,18 +1,3 @@
-/**
- * The namespace URIs the Open Packaging Conventions layer itself owns — the ones that describe a
- * *package* rather than the spreadsheet inside it. Every OOXML package carries these regardless of
- * which serialisation its office document uses, so an `.xlsb` and an `.xlsx` agree on them exactly.
- *
- * The SpreadsheetML vocabulary (the main namespace, DrawingML, the Microsoft extension URIs) is a
- * property of the XML codec and lives in `../xlsx/namespaces.ts`.
- */
-/** The `xmlns` of every `.rels` package relationships part. */
 export const PKG_RELS_NS = 'http://schemas.openxmlformats.org/package/2006/relationships';
-/** The `xmlns` of the package's `[Content_Types].xml`. */
 export const CONTENT_TYPES_NS = 'http://schemas.openxmlformats.org/package/2006/content-types';
-/**
- * Scopes both the relationship *type* URIs a `.rels` part declares and the `r:id` references a part's
- * body carries. Part-level rather than package-level in ECMA-376's own split, but it is the vocabulary
- * the relationship graph is written in, so it belongs with the graph and not with either codec.
- */
 export const RELATIONSHIPS_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';

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

@@ -1,26 +1,15 @@
-// The path algebra of an OPC package: a part's extension, where its relationships live, and how one
-// part names another. Pure string work over package-absolute paths, with no notion of what any part
-// contains — so the XML and BIFF12 codecs, and the readers and writers within each, share it.
-// Where the writer always puts the theme part. The workbook's theme relationship and the package's
-// content-type override both name this path unconditionally, so a theme preserved from a source
-// package that called its part something else is re-emitted here rather than at its original name.
 export const THEME_PART_PATH = 'xl/theme/theme1.xml';
-// The extension of a part path (`xl/media/image1.jpeg` → `jpeg`), or '' when it carries none.
 export function extensionOf(partPath) {
     const dot = partPath.lastIndexOf('.');
     const slash = partPath.lastIndexOf('/');
     return dot > slash ? partPath.slice(dot + 1) : '';
 }
-// The relationships part path for `dir/name.ext` → `dir/_rels/name.ext.rels`.
 export function relsPathFor(partPath) {
     const slash = partPath.lastIndexOf('/');
     const dir = slash === -1 ? '' : partPath.slice(0, slash + 1);
     const base = slash === -1 ? partPath : partPath.slice(slash + 1);
     return `${dir}_rels/${base}.rels`;
 }
-// A relationship target expressed relative to the part that carries it: the `..` hops out of the
-// referencing part's directory up to the common ancestor, then down to the target. Both paths are
-// package-absolute (`xl/drawings/preservedP1.vml` → `xl/media/preservedP2.jpeg` → `../media/preservedP2.jpeg`).
 export function relativePartPath(fromPath, toPath) {
     const fromDir = fromPath.split('/').slice(0, -1);
     const toSegments = toPath.split('/');