@lotics/xlsx 0.1.7 → 0.1.8

package/AGENTS.md

@@ -321,6 +321,12 @@ Each returns a `Command` (`{ description, execute, undo }`); run it and push it
 - Row/col insert/delete re-key populated cells and shift formula references (via
   `adjustMergedCells*` / `expandFormulaRangesForRowInsert`, also barrel-exported) — this is why they
   must be commands, not direct `SheetModel` edits.
+- Row/col insert/delete also **clamp the used range**: before shifting, they drop "phantom" cells —
+  value-less, unstyled, General-format padding outside the bounding box of the cells that carry data
+  or formatting. Real files accumulate these (a bloated stored `<dimension>` or a stray fill leaves
+  empty cells far past the data), and left in place they inflate the used range that drives the canvas
+  render width and the exported `<dimension>`. Undo restores them, and cells with any value, formula,
+  style, number format, or hyperlink are never dropped.
 
 ### Export to `.xlsx` bytes — `xlsx_writer.ts` (barrel)
 

package/package.json

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

package/src/spreadsheet_commands.test.ts

@@ -27,10 +27,15 @@ import {
   setShowGridLinesCommand,
   setShowHeadersCommand,
   setHyperlinkCommand,
+  insertRowsCommand,
+  deleteRowsCommand,
+  insertColsCommand,
+  deleteColsCommand,
 } from "./spreadsheet_commands";
 import { CommandHistory } from "./command_history";
 import { WorkbookModel, SheetModel, StyleRegistry } from "./workbook_model";
 import type { ChangeEvent } from "./workbook_model";
+import { rowColToRef, refToRowCol } from "./excel_utils";
 
 function makeWorkbook(): WorkbookModel {
   const styles = new StyleRegistry();
@@ -770,3 +775,107 @@ describe("setHyperlinkCommand", () => {
     expect(wb.sheets[0].hyperlinks.has("A1")).toBe(false);
   });
 });
+
+describe("structural ops clamp phantom cells", () => {
+  // A sheet whose real data ends at column C but that carries value-less,
+  // unstyled "phantom" cells out to column 40 in row 2 — the shape a bloated
+  // stored `<dimension>` (e.g. A1:XDD63) leaves behind. Left alone, these
+  // inflate the used range, driving the render width and exported dimension to
+  // the phantom extent.
+  function makeSheetWithJunkWidth(): WorkbookModel {
+    const wb = makeWorkbook();
+    const sheet = wb.sheets[0];
+    sheet.set("A1", "Name");
+    sheet.set("B1", "Qty");
+    sheet.set("C1", "Price");
+    sheet.set("A2", "Widget");
+    sheet.set("B2", 5);
+    sheet.set("C2", 10);
+    for (let c = 4; c <= 40; c++) sheet.set(rowColToRef(2, c), null);
+    return wb;
+  }
+
+  test("insert-rows drops phantom cells beyond the used-data columns", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    expect(sheet.getUsedRange().maxCol).toBe(40); // phantoms inflate it pre-op
+
+    insertRowsCommand(wb, 0, 2, 1).execute();
+
+    // Used range is clamped to the real data extent (column C = 3).
+    expect(sheet.getUsedRange().maxCol).toBe(3);
+    // No cell — in the inserted row or any other — exists beyond column C.
+    for (const ref of sheet.cells.keys()) {
+      expect(refToRowCol(ref)!.col).toBeLessThanOrEqual(3);
+    }
+    // Data is intact and shifted: row 2 is now blank, data moved to row 3.
+    expect(sheet.getCell("A3")?.value).toBe("Widget");
+  });
+
+  test("preserves an empty but styled cell — not a phantom", () => {
+    // A styles-wired sheet, as loaded from a file, so `set` can intern a style.
+    const styles = new StyleRegistry();
+    const sheet = new SheetModel("Sheet1", styles);
+    const wb = new WorkbookModel({ sheets: [sheet], activeSheetIndex: 0, styles });
+    sheet.set("A1", "data");
+    sheet.set("E1", null, { fontBold: true }); // empty yet meaningfully styled
+    expect(sheet.getCell("E1")?.styleIndex).not.toBe(0);
+
+    insertRowsCommand(wb, 0, 1, 1).execute();
+
+    // The styled empty cell survives (shifted to E2) and still extends the range.
+    expect(sheet.getUsedRange().maxCol).toBe(5);
+    expect(sheet.getCell("E2")?.styleIndex).not.toBe(0);
+  });
+
+  test("leaves phantom cells that sit inside the data bounding box", () => {
+    const wb = makeWorkbook();
+    const sheet = wb.sheets[0];
+    sheet.set("A1", "x");
+    sheet.set("C1", "y"); // data spans A1:C1
+    sheet.set("B1", null); // a phantom INSIDE the box — must not be dropped
+
+    insertRowsCommand(wb, 0, 1, 1).execute();
+
+    // B shifts to B2 and remains present; the box is unchanged.
+    expect(sheet.getCell("B2")).toBeDefined();
+    expect(sheet.getUsedRange().maxCol).toBe(3);
+  });
+
+  test("delete-rows also clamps phantom cells", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    deleteRowsCommand(wb, 0, 1, 1).execute();
+    expect(sheet.getUsedRange().maxCol).toBe(3);
+  });
+
+  test("insert-cols also clamps phantom cells", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    insertColsCommand(wb, 0, 1, 1).execute();
+    // Phantoms pruned; real data A:C shifted right to B:D.
+    expect(sheet.getUsedRange().maxCol).toBe(4);
+  });
+
+  test("delete-cols also clamps phantom cells", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    deleteColsCommand(wb, 0, 1, 1).execute();
+    // Phantoms pruned; B:C shifted left to A:B.
+    expect(sheet.getUsedRange().maxCol).toBe(2);
+  });
+
+  test("undo restores the pruned phantom cells", () => {
+    const wb = makeSheetWithJunkWidth();
+    const sheet = wb.sheets[0];
+    const beforeSize = sheet.cells.size;
+
+    const cmd = insertRowsCommand(wb, 0, 2, 1);
+    cmd.execute();
+    expect(sheet.getUsedRange().maxCol).toBe(3);
+
+    cmd.undo();
+    expect(sheet.cells.size).toBe(beforeSize);
+    expect(sheet.getUsedRange().maxCol).toBe(40);
+  });
+});

package/src/spreadsheet_commands.ts

@@ -9,7 +9,7 @@
 
 import type { Command } from "./command_history";
 import { SheetModel } from "./workbook_model";
-import type { WorkbookModel, CellValue } from "./workbook_model";
+import type { WorkbookModel, CellValue, CellModel } from "./workbook_model";
 import type { CellStyle, CellContent } from "./types";
 import type { ParsedConditionalFormat } from "./excel_cf_types";
 import type { FormulaEngine } from "./formula_engine";
@@ -319,6 +319,90 @@ export function unmergeCellsCommand(
   };
 }
 
+// =============================================================================
+// Phantom-cell clamping for structural row/column ops
+// =============================================================================
+//
+// Real-world .xlsx files accumulate "phantom" cells: value-less, unformatted
+// `<c>` elements that a stray fill-to-the-right or a bloated stored
+// `<dimension>` left behind (e.g. a sheet whose data ends at column G but that
+// carries empty cells out to column XDD). The parser materializes them
+// faithfully, so they land in the model carrying no data and no formatting —
+// yet they inflate the used range, which drives BOTH the canvas render width
+// and the exported `<dimension>`. A file bloated to column 16,332 renders ~1.5M
+// pixels wide.
+//
+// A structural row/column op is the natural normalization point (Excel itself
+// tightens the used range when you insert/delete): before shifting cells, we
+// drop phantom cells that lie OUTSIDE the bounding box of the cells that
+// actually carry information, clamping the sheet to its real extent. We never
+// drop a cell with a value, a formula, a non-default style, a number format, an
+// error, rich text, or a hyperlink — only truly inert padding.
+
+/**
+ * A cell carrying zero information: no value, no formula, the default (empty)
+ * style, the General number format, no error/rich-text, and plain empty
+ * content (so hyperlinks are excluded). Such a cell is indistinguishable from
+ * an absent cell — Excel renders and evaluates them identically.
+ */
+function isInertCell(cell: CellModel): boolean {
+  return (
+    (cell.value === null || cell.value === "") &&
+    cell.formula === undefined &&
+    cell.styleIndex === 0 &&
+    (cell.originalXfIndex === undefined || cell.originalXfIndex === 0) &&
+    (cell.numFmtCode === "General" || cell.numFmtCode === "") &&
+    cell.richText === undefined &&
+    cell.error === undefined &&
+    cell.content.type === "plain" &&
+    cell.content.text === ""
+  );
+}
+
+/**
+ * Drop inert phantom cells that fall outside the bounding box of the sheet's
+ * meaningful (non-inert) cells, clamping the used range to its real extent.
+ * Returns the removed cells keyed by ref so the caller can restore them on undo.
+ */
+function clampInertCells(sheet: SheetModel): Map<string, CellModel> {
+  let minRow = Infinity;
+  let maxRow = 0;
+  let minCol = Infinity;
+  let maxCol = 0;
+  let hasMeaningful = false;
+  for (const [ref, cell] of sheet.cells) {
+    if (isInertCell(cell)) continue;
+    const rc = refToRowColSafe(ref);
+    if (!rc) continue;
+    hasMeaningful = true;
+    if (rc.row < minRow) minRow = rc.row;
+    if (rc.row > maxRow) maxRow = rc.row;
+    if (rc.col < minCol) minCol = rc.col;
+    if (rc.col > maxCol) maxCol = rc.col;
+  }
+
+  const pruned = new Map<string, CellModel>();
+  for (const [ref, cell] of sheet.cells) {
+    if (!isInertCell(cell)) continue;
+    // No meaningful cells at all → every phantom is padding. Otherwise, only
+    // phantoms strictly outside the meaningful bounding box are padding; a
+    // phantom interspersed with real data is left untouched (it doesn't inflate
+    // the used range and dropping it would be a needless mutation).
+    if (!hasMeaningful) {
+      pruned.set(ref, cell);
+      continue;
+    }
+    const rc = refToRowColSafe(ref);
+    if (!rc) continue;
+    if (rc.row < minRow || rc.row > maxRow || rc.col < minCol || rc.col > maxCol) {
+      pruned.set(ref, cell);
+    }
+  }
+
+  for (const ref of pruned.keys()) sheet.cells.delete(ref);
+  return pruned;
+}
+
 // =============================================================================
 // Insert Rows
 // =============================================================================
@@ -334,11 +418,13 @@ export function insertRowsCommand(
   // the inverse of `adjustMergedCellsForRowInsert` and avoids edge cases when
   // inserts split existing ranges.
   let mergeSnapshot: string[] = [];
+  let inertSnapshot = new Map<string, CellModel>();
 
   return {
     description: `Insert ${count} row${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       // Shift existing cells down
       const toMove: Array<{ ref: string; row: number; col: number }> = [];
       for (const [ref] of sheet.cells) {
@@ -388,6 +474,7 @@ export function insertRowsCommand(
         sheet.rowHeights.set(r - count, h);
       }
       for (let r = at; r < at + count; r++) sheet.rowHeights.delete(r);
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "rows_deleted", sheet: sheetIndex, at, count });
     },
   };
@@ -413,11 +500,13 @@ export function deleteRowsCommand(
     }
   }
   let mergeSnapshot: string[] = [];
+  let inertSnapshot = new Map<string, CellModel>();
 
   return {
     description: `Delete ${count} row${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       // Delete cells in the range
       for (const ref of snapshot.keys()) sheet.cells.delete(ref);
       // Shift cells up
@@ -454,6 +543,7 @@ export function deleteRowsCommand(
       for (const [ref, snap] of snapshot) {
         sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
       }
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "rows_inserted", sheet: sheetIndex, at, count });
     },
   };
@@ -471,11 +561,13 @@ export function insertColsCommand(
 ): Command {
   const sheet = workbook.sheets[sheetIndex];
   let mergeSnapshot: string[] = [];
+  let inertSnapshot = new Map<string, CellModel>();
 
   return {
     description: `Insert ${count} column${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       const toMove: Array<{ ref: string; row: number; col: number }> = [];
       for (const [ref] of sheet.cells) {
         const rc = refToRowColSafe(ref);
@@ -519,6 +611,7 @@ export function insertColsCommand(
         sheet.colWidths.set(c - count, w);
       }
       for (let c = at; c < at + count; c++) sheet.colWidths.delete(c);
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "cols_deleted", sheet: sheetIndex, at, count });
     },
   };
@@ -543,11 +636,13 @@ export function deleteColsCommand(
     }
   }
   let mergeSnapshot: string[] = [];
+  let inertSnapshot = new Map<string, CellModel>();
 
   return {
     description: `Delete ${count} column${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       for (const ref of snapshot.keys()) sheet.cells.delete(ref);
       const toMove: Array<{ ref: string; row: number; col: number }> = [];
       for (const [ref] of sheet.cells) {
@@ -580,6 +675,7 @@ export function deleteColsCommand(
       for (const [ref, snap] of snapshot) {
         sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
       }
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "cols_inserted", sheet: sheetIndex, at, count });
     },
   };