@lotics/xlsx 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/xlsx",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/data_workbook.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from "vitest";
+import { buildDataWorkbook } from "./data_workbook";
+import { exportWorkbook } from "./xlsx_writer";
+import { parseExcelBuffer } from "./excel_parser";
+import { parseToExcelSerial } from "./numfmt_type";
+import type { ParsedSheet, ParsedCell } from "./types";
+
+interface FeeRow {
+  container: string;
+  date: Date | null;
+  amount: number | null;
+  count: number;
+}
+
+const ROWS: FeeRow[] = [
+  { container: "ABCD1234567", date: new Date(2026, 5, 15), amount: 1_500_000, count: 2 },
+  { container: "WXYZ7654321", date: null, amount: null, count: 0 },
+];
+
+function roundTrip<R>(opts: Parameters<typeof buildDataWorkbook<R>>[0]): ParsedSheet {
+  const wb = buildDataWorkbook(opts);
+  const bytes = exportWorkbook(wb);
+  // Fresh, tightly-sized ArrayBuffer for the parser.
+  const parsed = parseExcelBuffer(new Uint8Array(bytes).buffer);
+  return parsed.sheets[0];
+}
+
+function cellAt(sheet: ParsedSheet, row: number, col: number): ParsedCell | undefined {
+  return sheet.rows.find((r) => r.index === row)?.cells.find((c) => c.column === col);
+}
+
+describe("buildDataWorkbook", () => {
+  it("writes a header row and typed body cells that survive an .xlsx round-trip", () => {
+    const sheet = roundTrip<FeeRow>({
+      sheetName: "Phí",
+      currencyFormat: '#,##0" ₫"',
+      columns: [
+        { header: "Container", value: (r) => r.container },
+        { header: "Ngày", type: "date", value: (r) => r.date },
+        { header: "Số tiền", type: "currency", value: (r) => r.amount },
+        { header: "Số khoản", type: "integer", value: (r) => r.count },
+      ],
+      rows: ROWS,
+    });
+
+    expect(sheet.name).toBe("Phí");
+
+    // Header row (row 1).
+    expect(cellAt(sheet, 1, 1)?.value).toBe("Container");
+    expect(cellAt(sheet, 1, 2)?.value).toBe("Ngày");
+    expect(cellAt(sheet, 1, 3)?.value).toBe("Số tiền");
+    expect(cellAt(sheet, 1, 4)?.value).toBe("Số khoản");
+    expect(cellAt(sheet, 1, 1)?.style?.fontBold).toBe(true);
+
+    // Data row 1 (row 2): text + real date serial + numeric amount.
+    expect(cellAt(sheet, 2, 1)?.value).toBe("ABCD1234567");
+    expect(cellAt(sheet, 2, 2)?.rawValue).toBe(parseToExcelSerial("2026-06-15"));
+    expect(cellAt(sheet, 2, 3)?.rawValue).toBe(1_500_000);
+    expect(cellAt(sheet, 2, 4)?.rawValue).toBe(2);
+  });
+
+  it("preserves leading zeros on numeric-looking text (tax IDs, phone numbers)", () => {
+    // A text cell whose content looks like a number must round-trip as the exact
+    // string — fast-xml-parser's default tag coercion would otherwise read the
+    // shared-string `<t>0312345678</t>` as 312345678 and drop the leading zero.
+    const sheet = roundTrip<{ mst: string }>({
+      columns: [{ header: "MST", type: "text", value: (r) => r.mst }],
+      rows: [{ mst: "0312345678" }, { mst: "0001" }],
+    });
+    expect(cellAt(sheet, 2, 1)?.value).toBe("0312345678");
+    expect(cellAt(sheet, 3, 1)?.value).toBe("0001");
+  });
+
+  it("leaves null cells empty rather than writing zeros or blanks", () => {
+    const sheet = roundTrip<FeeRow>({
+      columns: [
+        { header: "Container", value: (r) => r.container },
+        { header: "Ngày", type: "date", value: (r) => r.date },
+        { header: "Số tiền", type: "currency", value: (r) => r.amount },
+      ],
+      rows: ROWS,
+    });
+
+    // Row 3 = ROWS[1], whose date + amount are null → no cells there.
+    expect(cellAt(sheet, 3, 1)?.value).toBe("WXYZ7654321");
+    expect(cellAt(sheet, 3, 2)).toBeUndefined();
+    expect(cellAt(sheet, 3, 3)).toBeUndefined();
+  });
+
+  it("sanitizes an invalid sheet name and defaults an empty one", () => {
+    const named = roundTrip<FeeRow>({
+      sheetName: "Phí/2026:Q2",
+      columns: [{ header: "C", value: (r) => r.container }],
+      rows: ROWS,
+    });
+    expect(named.name).toBe("Phí 2026 Q2");
+  });
+
+  it("auto-fits column width to the widest of header and content", () => {
+    const wb = buildDataWorkbook<FeeRow>({
+      columns: [
+        { header: "C", value: (r) => r.container }, // content (11 chars) wider than header
+        { header: "Fixed", value: (r) => r.container, width: 40 },
+      ],
+      rows: ROWS,
+    });
+    const widths = wb.sheets[0].colWidths;
+    expect(widths.get(1)).toBe(13); // 11 content + 2 padding
+    expect(widths.get(2)).toBe(40); // explicit override wins
+  });
+});

package/src/data_workbook.ts

@@ -0,0 +1,186 @@
+// =============================================================================
+// buildDataWorkbook — tabular data → a styled, ready-to-export WorkbookModel
+// =============================================================================
+//
+// The companion to `exportWorkbook` for the common "I have rows, give me an
+// .xlsx" case (a query result, a report, a register). Without it every caller
+// re-hand-rolls the same header styling, number formats, date-serial math, and
+// column sizing. Columns are declared once with a type + a `value` accessor;
+// the helper writes a bold frozen header row, per-type number formats (dates as
+// real Excel serials, currency via a caller-supplied format), and auto-fit
+// widths. Returns a `WorkbookModel` — the caller pairs it with `exportWorkbook`.
+
+import { WorkbookModel, SheetModel, StyleRegistry, type CellValue } from "./workbook_model";
+import type { CellStyle } from "./types";
+import { rowColToRef } from "./excel_utils";
+import { parseToExcelSerial } from "./numfmt_type";
+
+/** How a column's cells are typed and formatted. */
+export type DataColumnType = "text" | "integer" | "number" | "currency" | "date";
+
+export interface DataColumn<R> {
+  /** Header text, written to row 1. */
+  header: string;
+  /**
+   * The cell value for a row. Return `null`/`undefined` for an empty cell. A
+   * `date` column may return a `Date` or an ISO `YYYY-MM-DD` string; numeric
+   * columns may return a number or a numeric string (coerced).
+   */
+  value: (row: R) => string | number | Date | null | undefined;
+  /** Cell type — drives number format + alignment. Default `"text"`. */
+  type?: DataColumnType;
+  /** Column width in characters. Default: auto-fit from header + sampled rows. */
+  width?: number;
+}
+
+export interface BuildDataWorkbookOptions<R> {
+  columns: DataColumn<R>[];
+  rows: readonly R[];
+  /** Sheet (tab) name. Default `"Sheet1"`. Sanitized to Excel's rules. */
+  sheetName?: string;
+  /** Number format for `currency` columns. Default `"#,##0"` (no decimals). */
+  currencyFormat?: string;
+  /** Number format for `date` columns. Default `"dd/mm/yyyy"`. */
+  dateFormat?: string;
+  /** Override the header-row style. */
+  headerStyle?: CellStyle;
+}
+
+const DEFAULT_CURRENCY_FORMAT = "#,##0";
+const DEFAULT_DATE_FORMAT = "dd/mm/yyyy";
+const INTEGER_FORMAT = "#,##0";
+const NUMBER_FORMAT = "#,##0.##";
+
+const DEFAULT_HEADER_STYLE: CellStyle = {
+  fontBold: true,
+  backgroundColor: "#F4F4F5",
+  verticalAlign: "middle",
+  borderBottom: { width: 1, style: "thin", color: "#D4D4D8" },
+};
+
+const RIGHT_ALIGN: ReadonlySet<DataColumnType> = new Set<DataColumnType>([
+  "integer",
+  "number",
+  "currency",
+]);
+
+// Excel sheet names: ≤ 31 chars, none of : \ / ? * [ ], non-empty.
+function sanitizeSheetName(name: string): string {
+  const cleaned = name.replace(/[:\\/?*[\]]/g, " ").trim().slice(0, 31);
+  return cleaned || "Sheet1";
+}
+
+function numFmtFor(type: DataColumnType, currencyFormat: string, dateFormat: string): string | undefined {
+  switch (type) {
+    case "currency":
+      return currencyFormat;
+    case "integer":
+      return INTEGER_FORMAT;
+    case "number":
+      return NUMBER_FORMAT;
+    case "date":
+      return dateFormat;
+    case "text":
+      return undefined;
+  }
+}
+
+/** Local `YYYY-MM-DD` for a Date (date-only — fee dates carry no meaningful time). */
+function toLocalIsoDate(d: Date): string {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+/** Coerce a raw accessor result to the cell value + the text used for width fit. */
+function coerce(
+  raw: string | number | Date | null | undefined,
+  type: DataColumnType,
+): { value: CellValue; sample: string } {
+  if (raw === null || raw === undefined || raw === "") return { value: null, sample: "" };
+
+  if (type === "date") {
+    const iso = raw instanceof Date ? toLocalIsoDate(raw) : typeof raw === "string" ? raw : null;
+    const serial = iso ? parseToExcelSerial(iso) : null;
+    // Unparseable date → fall back to its text so nothing is silently dropped.
+    if (serial === null) return { value: String(raw), sample: String(raw) };
+    return { value: serial, sample: raw instanceof Date ? toLocalIsoDate(raw) : String(raw) };
+  }
+
+  if (RIGHT_ALIGN.has(type)) {
+    const n = typeof raw === "number" ? raw : Number(raw);
+    if (!Number.isFinite(n)) return { value: String(raw), sample: String(raw) };
+    return { value: n, sample: n.toLocaleString("en-US") };
+  }
+
+  const str = raw instanceof Date ? toLocalIsoDate(raw) : String(raw);
+  return { value: str, sample: str };
+}
+
+function clampWidth(chars: number): number {
+  return Math.min(60, Math.max(8, Math.ceil(chars) + 2));
+}
+
+/**
+ * Build a single-sheet workbook from typed columns + rows.
+ *
+ * ```ts
+ * const wb = buildDataWorkbook({
+ *   sheetName: "Phí",
+ *   currencyFormat: '#,##0" ₫"',
+ *   columns: [
+ *     { header: "Container", value: (r) => r.container },
+ *     { header: "Ngày", type: "date", value: (r) => r.date },
+ *     { header: "Số tiền", type: "currency", value: (r) => r.amount },
+ *   ],
+ *   rows,
+ * });
+ * const bytes = exportWorkbook(wb);
+ * ```
+ */
+export function buildDataWorkbook<R>(opts: BuildDataWorkbookOptions<R>): WorkbookModel {
+  const {
+    columns,
+    rows,
+    sheetName = "Sheet1",
+    currencyFormat = DEFAULT_CURRENCY_FORMAT,
+    dateFormat = DEFAULT_DATE_FORMAT,
+    headerStyle = DEFAULT_HEADER_STYLE,
+  } = opts;
+
+  const styles = new StyleRegistry();
+  const sheet = new SheetModel(sanitizeSheetName(sheetName), styles);
+
+  // Per-type body cell style (interned once each via the StyleRegistry).
+  const bodyStyleFor = (type: DataColumnType): CellStyle | undefined =>
+    RIGHT_ALIGN.has(type) ? { horizontalAlign: "right" } : undefined;
+
+  // Cap width sampling so a huge export doesn't scan every row for sizing.
+  const widthSampleRows = rows.slice(0, 1000);
+
+  columns.forEach((col, c) => {
+    const type = col.type ?? "text";
+    const numFmt = numFmtFor(type, currencyFormat, dateFormat);
+    const bodyStyle = bodyStyleFor(type);
+
+    // Header.
+    sheet.set(rowColToRef(1, c + 1), col.header, headerStyle);
+
+    // Body.
+    let maxSample = col.header.length;
+    rows.forEach((rowData, r) => {
+      const { value, sample } = coerce(col.value(rowData), type);
+      if (r < widthSampleRows.length && sample.length > maxSample) maxSample = sample.length;
+      if (value === null) return; // leave empty cells truly empty
+      sheet.set(rowColToRef(r + 2, c + 1), value, bodyStyle, numFmt);
+    });
+
+    sheet.colWidths.set(c + 1, col.width ?? clampWidth(maxSample));
+  });
+
+  // Freeze the header row.
+  if (rows.length > 0 || columns.length > 0) sheet.setFreeze("A2");
+
+  return new WorkbookModel({ sheets: [sheet], activeSheetIndex: 0, styles });
+}

package/src/excel_parser.test.ts

@@ -352,7 +352,7 @@ describe("parseExcelFile", () => {
     expect(merge.endCol).toBe(3);
   });
 
-  test("skips hidden sheets", async () => {
+  test("includes hidden sheets, flagged so renderers can skip them", async () => {
     const workbook = new ExcelJS.Workbook();
     workbook.addWorksheet("Visible");
     const hidden = workbook.addWorksheet("Hidden");
@@ -363,9 +363,11 @@ describe("parseExcelFile", () => {
 
     const result = await parseExcelFile("https://example.com/test.xlsx");
 
-
-    expect(result.sheets).toHaveLength(1);
-    expect(result.sheets[0].name).toBe("Visible");
+    // The parser preserves hidden sheets (data consumers still read them) and
+    // marks them via `hidden` so renderers can choose to skip them.
+    expect(result.sheets.map((s) => s.name)).toEqual(["Visible", "Hidden"]);
+    expect(result.sheets[0].hidden).toBeFalsy();
+    expect(result.sheets[1].hidden).toBe(true);
   });
 
   test("preserves cell text when <v> carries xml:space=\"preserve\"", () => {

package/src/excel_parser.ts

@@ -54,31 +54,52 @@ export type {
 // Parsing
 // =============================================================================
 
+/**
+ * Options controlling how a workbook is parsed.
+ */
+export interface ParseOptions {
+  /**
+   * Maximum number of data rows to parse per sheet. Defaults to a preview
+   * guard (10_000) that protects the canvas renderer from pathological
+   * sheets. Pass `Infinity` for full data extraction (e.g. importing a
+   * sheet into a table) — `ParsedSheet.truncated` reports whether the limit
+   * was hit.
+   */
+  maxRowsPerSheet?: number;
+}
+
 export async function parseExcelFile(
   url: string,
   signal?: AbortSignal,
+  options?: ParseOptions,
 ): Promise<ParsedSpreadsheet> {
   const response = await fetch(url, { signal });
   if (!response.ok) {
     throw new Error(`Failed to fetch file: ${response.status} ${response.statusText}`);
   }
-  return parseExcelBuffer(await response.arrayBuffer());
+  return parseExcelBuffer(await response.arrayBuffer(), options);
 }
 
 /**
  * Parse an in-memory .xlsx buffer into a ParsedSpreadsheet.
  * Use this when you already have the bytes (e.g. from File.arrayBuffer()).
  */
-export function parseExcelBuffer(arrayBuffer: ArrayBuffer): ParsedSpreadsheet {
+export function parseExcelBuffer(
+  arrayBuffer: ArrayBuffer,
+  options?: ParseOptions,
+): ParsedSpreadsheet {
   const zip = unzipXlsx(arrayBuffer);
-  return parseExcelFromZip(zip);
+  return parseExcelFromZip(zip, options);
 }
 
 /**
  * Parse from already-unzipped entries. Use this when you need both the
  * ParsedSpreadsheet and the raw ZIP entries (e.g. for delta export).
  */
-export function parseExcelFromZip(zip: Record<string, Uint8Array>): ParsedSpreadsheet {
+export function parseExcelFromZip(
+  zip: Record<string, Uint8Array>,
+  options?: ParseOptions,
+): ParsedSpreadsheet {
   // Parse theme
   const themeEntry = findEntry(zip, "xl/theme/theme1.xml");
   const theme: ThemeData = themeEntry
@@ -190,6 +211,7 @@ export function parseExcelFromZip(zip: Record<string, Uint8Array>): ParsedSpread
       styles.indexedColors,
       zip,
       workbookInfo.date1904,
+      options?.maxRowsPerSheet,
     );
     parsed.name = sheetInfo.name;
     if (isHidden) parsed.hidden = true;

package/src/hidden_rows_round_trip.test.ts

@@ -0,0 +1,75 @@
+// =============================================================================
+// Hidden rows are data, not throwaway — they must survive a parse → write → parse
+// round-trip.
+// =============================================================================
+//
+// Regression: the OOXML row parser dropped hidden rows entirely (`continue`)
+// instead of flagging them. On a real customer workbook — an INV&PKL export form
+// whose BBGH tab pulls its line items from a master sheet via cross-sheet formulas,
+// with hidden spacer rows interleaved through the line block — a single edit + save
+// lost the whole line table: the hidden rows vanished outright, and the visible rows
+// around them broke because their cross-sheet formulas now referenced rows that no
+// longer existed in the model. Columns were always parsed-and-flagged (parseCols);
+// rows must behave the same.
+//
+// Built entirely on the package's own model → export → parse path (no ExcelJS), so
+// it exercises the fixed parser directly.
+
+import { describe, it, expect } from "vitest";
+import { exportWorkbook } from "./xlsx_writer";
+import { parseExcelBuffer } from "./excel_parser";
+import { WorkbookModel, SheetModel, StyleRegistry } from "./workbook_model";
+
+function buildHiddenRowWorkbook(): WorkbookModel {
+  const styles = new StyleRegistry();
+
+  // Master sheet: 6 line rows, all with data; rows 2 and 5 hidden (spacers).
+  const data = new SheetModel("Data", styles);
+  for (let r = 1; r <= 6; r++) {
+    data.set(`A${r}`, r);
+    data.set(`B${r}`, `item ${r}`);
+  }
+  data.hiddenRows.add(2);
+  data.hiddenRows.add(5);
+
+  // View sheet: each cell mirrors a Data row via a cross-sheet formula —
+  // including the hidden rows. (value = cached result, formula = the ref.)
+  const view = new SheetModel("View", styles);
+  for (let r = 1; r <= 6; r++) {
+    view.set(`A${r}`, `item ${r}`, undefined, undefined, `Data!B${r}`);
+  }
+
+  return new WorkbookModel({ sheets: [data, view], activeSheetIndex: 0, styles });
+}
+
+describe("xlsx hidden rows round-trip", () => {
+  it("keeps hidden rows (values + hidden flag) and the cross-sheet refs into them", () => {
+    const exported = exportWorkbook(buildHiddenRowWorkbook());
+    const reparsed = parseExcelBuffer(exported.buffer as ArrayBuffer);
+
+    const dataSheet = reparsed.sheets.find((s) => s.name === "Data")!;
+    const rowIndexes = dataSheet.rows.map((r) => r.index).sort((a, b) => a - b);
+    // All six rows survive — not just the visible ones.
+    expect(rowIndexes).toEqual([1, 2, 3, 4, 5, 6]);
+
+    const cellVal = (sheetName: string, r: number, col: number) => {
+      const sheet = reparsed.sheets.find((s) => s.name === sheetName)!;
+      return sheet.rows.find((row) => row.index === r)?.cells.find((c) => c.column === col)?.value;
+    };
+
+    // Hidden rows keep their data.
+    expect(cellVal("Data", 2, 2)).toBe("item 2");
+    expect(cellVal("Data", 5, 2)).toBe("item 5");
+    // Visible row after the last hidden row survives (no cascade loss).
+    expect(cellVal("Data", 6, 2)).toBe("item 6");
+
+    // The hidden flag round-trips on exactly the hidden rows.
+    const hidden = new Set(dataSheet.rows.filter((r) => r.hidden).map((r) => r.index));
+    expect(hidden).toEqual(new Set([2, 5]));
+
+    // Cross-sheet references into the hidden rows still resolve to their cached values.
+    expect(cellVal("View", 2, 1)).toBe("item 2");
+    expect(cellVal("View", 5, 1)).toBe("item 5");
+    expect(cellVal("View", 6, 1)).toBe("item 6");
+  });
+});

package/src/index.ts

@@ -98,8 +98,17 @@ export {
   parseExcelFromZip,
 } from "./excel_parser";
 
+export type { ParseOptions } from "./excel_parser";
+
 export { exportWorkbook } from "./xlsx_writer";
 
+// -----------------------------------------------------------------------------
+// Data → workbook (the common "rows in, .xlsx out" helper)
+// -----------------------------------------------------------------------------
+
+export { buildDataWorkbook } from "./data_workbook";
+export type { DataColumn, DataColumnType, BuildDataWorkbookOptions } from "./data_workbook";
+
 export { unzipXlsx } from "./ooxml_zip";
 
 // -----------------------------------------------------------------------------

package/src/ooxml_sheet.ts

@@ -114,6 +114,7 @@ export function parseSheet(
   indexedColors: string[],
   zipEntries: Record<string, Uint8Array>,
   date1904: boolean,
+  maxRows: number = MAX_ROWS_PER_SHEET,
 ): ParsedSheet {
   const doc = xmlParser.parse(sheetXml);
   const worksheet = doc?.["worksheet"];
@@ -148,7 +149,7 @@ export function parseSheet(
     maxCol,
     maxContentWidth,
     rowOutlineLevels,
-  } = parseSheetData(worksheet, styles, sharedStrings, hyperlinkMap, defaultRowHeight, date1904);
+  } = parseSheetData(worksheet, styles, sharedStrings, hyperlinkMap, defaultRowHeight, date1904, maxRows);
 
   // Build final columns from parsed col defs and data bounds
   const colCount = Math.max(parsedCols.length > 0 ? parsedCols[parsedCols.length - 1].max : 0, maxCol);
@@ -425,6 +426,7 @@ function parseSheetData(
   hyperlinkMap: Map<string, string>,
   defaultRowHeight: number,
   date1904: boolean,
+  maxRows: number,
 ): {
   rows: ParsedRow[];
   totalRowCount: number;
@@ -477,12 +479,16 @@ function parseSheetData(
       rowOutlineLevels.set(rowIndex, outlineLevel);
     }
 
-    // Skip hidden rows
-    if (rowEl["@_hidden"] === "1" || rowEl["@_hidden"] === "true") continue;
+    // Hidden rows are real data — keep them, flagged hidden, so they round-trip.
+    // Excel preserves hidden rows; dropping them silently loses the row on the next
+    // write AND breaks any cross-sheet formula that references it (the reference
+    // resolves to an empty cell), which cascades into whole blocks being lost.
+    // Columns already do this (parseCols flags hidden cols rather than skipping).
+    const rowHidden = rowEl["@_hidden"] === "1" || rowEl["@_hidden"] === "true";
 
     // Truncation check
     rowCount++;
-    if (rowCount > MAX_ROWS_PER_SHEET) continue;
+    if (rowCount > maxRows) continue;
 
     const height = rowEl["@_ht"]
       ? parseFloat(rowEl["@_ht"] as string)
@@ -498,8 +504,9 @@ function parseSheetData(
           cells.push(parsed);
           if (parsed.column > maxCol) maxCol = parsed.column;
 
-          // Track content width (sample first 200 rows)
-          if (rowCount <= 200) {
+          // Track content width (sample first 200 rows; hidden rows don't drive
+          // visible column auto-width)
+          if (rowCount <= 200 && !rowHidden) {
             const currentMax = maxContentWidth.get(parsed.column) ?? 0;
             if (parsed.value.length > currentMax) {
               maxContentWidth.set(parsed.column, parsed.value.length);
@@ -513,14 +520,14 @@ function parseSheetData(
       index: rowIndex,
       height,
       cells,
-      hidden: false,
+      hidden: rowHidden,
     });
   }
 
   return {
     rows,
     totalRowCount,
-    truncated: rowCount > MAX_ROWS_PER_SHEET,
+    truncated: rowCount > maxRows,
     maxCol,
     maxContentWidth,
     rowOutlineLevels,
@@ -592,11 +599,15 @@ function parseCell(
   let arrayRange: string | undefined;
   if (fEl !== undefined && fEl !== null) {
     if (typeof fEl === "object") {
-      const fObj = fEl as Record<string, string>;
-      formula = fObj["#text"];
+      const fObj = fEl as Record<string, unknown>;
+      // fast-xml-parser coerces numeric formula text (e.g. `<f ca="1">2026</f>`)
+      // to a number, so `#text` is not guaranteed to be a string.
+      const text = fObj["#text"];
+      formula = text == null ? undefined : String(text);
       if (fObj["@_t"] === "array") {
         isArrayFormula = true;
-        arrayRange = fObj["@_ref"];
+        const ref = fObj["@_ref"];
+        arrayRange = ref == null ? undefined : String(ref);
         // Strip {} braces from array formula text
         if (formula?.startsWith("{") && formula.endsWith("}")) {
           formula = formula.slice(1, -1);

package/src/ooxml_workbook.ts

@@ -37,6 +37,12 @@ export interface SharedStringEntry {
 const xmlParser = new XMLParser({
   ignoreAttributes: false,
   attributeNamePrefix: "@_",
+  // Shared-string and workbook text is textual BY DEFINITION (tax IDs, phone
+  // numbers, account codes, sheet/defined names). fast-xml-parser's default tag
+  // coercion would parse `<t>0312345678</t>` as the number 312345678 — silently
+  // dropping the leading zero before we can read it. Cell `<v>` numerics are
+  // parsed deliberately (parseFloat) in ooxml_sheet.ts, so this never affects them.
+  parseTagValue: false,
   trimValues: false,
   processEntities: false,
   isArray: (tagName) =>