@lotics/xlsx 0.1.0

package/src/clipboard.ts

@@ -0,0 +1,341 @@
+// =============================================================================
+// Clipboard — Copy/Cut/Paste for Spreadsheet
+// =============================================================================
+//
+// Handles copy, cut, and paste operations:
+// - Stores cell data in an internal buffer for paste
+// - Generates plain text and HTML for system clipboard
+// - Adjusts formula references on paste (relative shift)
+// =============================================================================
+
+import type { CellValue, WorkbookModel } from "./workbook_model";
+import { rowColToRef, colNumToLetters, colLettersToNum } from "./excel_utils";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ClipboardData {
+  /** Source sheet index. */
+  sourceSheet: number;
+  /** Source range (top-left). */
+  origin: { row: number; col: number };
+  /** Cell data grid (rows of cols). Undefined entries are empty cells. */
+  cells: (ClipboardCell | undefined)[][];
+  /** Number of rows in the selection. */
+  rowCount: number;
+  /** Number of columns in the selection. */
+  colCount: number;
+  /** Whether this was a cut (vs copy). Cut clears source on paste. */
+  isCut: boolean;
+}
+
+export interface ClipboardCell {
+  value: CellValue;
+  displayValue: string;
+  formula?: string;
+  styleIndex: number;
+  numFmtCode: string;
+}
+
+// =============================================================================
+// Copy
+// =============================================================================
+
+export function copyRange(
+  workbook: WorkbookModel,
+  sheetIndex: number,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+  isCut = false,
+): ClipboardData {
+  const sheet = workbook.sheets[sheetIndex];
+  const rowCount = endRow - startRow + 1;
+  const colCount = endCol - startCol + 1;
+  const cells: (ClipboardCell | undefined)[][] = [];
+
+  for (let r = 0; r < rowCount; r++) {
+    const row: (ClipboardCell | undefined)[] = [];
+    for (let c = 0; c < colCount; c++) {
+      const ref = rowColToRef(startRow + r, startCol + c);
+      const cell = sheet.getCell(ref);
+      if (cell) {
+        row.push({
+          value: cell.value,
+          displayValue: cell.displayValue,
+          formula: cell.formula,
+          styleIndex: cell.styleIndex,
+          numFmtCode: cell.numFmtCode,
+        });
+      } else {
+        row.push(undefined);
+      }
+    }
+    cells.push(row);
+  }
+
+  return {
+    sourceSheet: sheetIndex,
+    origin: { row: startRow, col: startCol },
+    cells,
+    rowCount,
+    colCount,
+    isCut,
+  };
+}
+
+// =============================================================================
+// Paste
+// =============================================================================
+
+export interface PasteResult {
+  /** Cells that were written. Array of { ref, value, formula, styleIndex }. */
+  written: Array<{ ref: string; value: CellValue; formula?: string; styleIndex: number }>;
+}
+
+export function pasteRange(
+  workbook: WorkbookModel,
+  clipboard: ClipboardData,
+  targetSheet: number,
+  targetRow: number,
+  targetCol: number,
+): PasteResult {
+  const sheet = workbook.sheets[targetSheet];
+  const written: PasteResult["written"] = [];
+
+  const dRow = targetRow - clipboard.origin.row;
+  const dCol = targetCol - clipboard.origin.col;
+
+  for (let r = 0; r < clipboard.rowCount; r++) {
+    for (let c = 0; c < clipboard.colCount; c++) {
+      const src = clipboard.cells[r][c];
+      if (!src) continue;
+
+      const ref = rowColToRef(targetRow + r, targetCol + c);
+      let formula = src.formula;
+
+      // Adjust formula references for relative paste
+      if (formula && !clipboard.isCut) {
+        formula = adjustFormulaRefs(formula, dRow, dCol);
+      }
+
+      sheet.set(ref, src.value, sheet.styles?.get(src.styleIndex), src.numFmtCode, formula);
+      written.push({ ref, value: src.value, formula, styleIndex: src.styleIndex });
+    }
+  }
+
+  return { written };
+}
+
+// =============================================================================
+// Plain text export (for system clipboard)
+// =============================================================================
+
+export function clipboardToText(clipboard: ClipboardData): string {
+  const lines: string[] = [];
+  for (const row of clipboard.cells) {
+    const values = row.map((c) => c?.displayValue ?? "");
+    lines.push(values.join("\t"));
+  }
+  return lines.join("\n");
+}
+
+// =============================================================================
+// HTML export (for rich paste)
+// =============================================================================
+
+export function clipboardToHtml(clipboard: ClipboardData, styles: WorkbookModel["styles"]): string {
+  let html = "<table>";
+  for (const row of clipboard.cells) {
+    html += "<tr>";
+    for (const cell of row) {
+      if (!cell) {
+        html += "<td></td>";
+        continue;
+      }
+      const style = styles.get(cell.styleIndex);
+      let css = "";
+      if (style.fontBold) css += "font-weight:bold;";
+      if (style.fontItalic) css += "font-style:italic;";
+      if (style.fontColor) css += `color:${style.fontColor};`;
+      if (style.backgroundColor) css += `background-color:${style.backgroundColor};`;
+      if (style.fontSize) css += `font-size:${style.fontSize}pt;`;
+      html += `<td${css ? ` style="${css}"` : ""}>${escapeHtml(cell.displayValue)}</td>`;
+    }
+    html += "</tr>";
+  }
+  html += "</table>";
+  return html;
+}
+
+// =============================================================================
+// Formula reference adjustment
+// =============================================================================
+
+/** Adjust cell references in a formula by the given row/col offsets. */
+export function adjustFormulaRefs(formula: string, dRow: number, dCol: number): string {
+  // Match cell references like A1, $A1, A$1, $A$1, Sheet1!A1
+  return formula.replace(
+    /(\$?)([A-Z]+)(\$?)(\d+)/g,
+    (_match, colAbsolute: string, colLetters: string, rowAbsolute: string, rowStr: string) => {
+      const colNum = colLettersToNum(colLetters);
+      const rowNum = parseInt(rowStr, 10);
+
+      const newCol = colAbsolute ? colNum : colNum + dCol;
+      const newRow = rowAbsolute ? rowNum : rowNum + dRow;
+
+      if (newCol < 1 || newRow < 1) return "#REF!";
+
+      return `${colAbsolute}${colNumToLetters(newCol)}${rowAbsolute}${newRow}`;
+    },
+  );
+}
+
+/**
+ * Adjust formula references for row insert/delete.
+ * Shifts row references >= `atRow` by `delta` (positive = insert, negative = delete).
+ * References to deleted rows become #REF!.
+ */
+export function adjustFormulaRefsForRowShift(
+  formula: string,
+  atRow: number,
+  delta: number,
+): string {
+  return formula.replace(
+    /(\$?)([A-Z]+)(\$?)(\d+)/g,
+    (_match, colAbs: string, colLetters: string, rowAbs: string, rowStr: string) => {
+      const rowNum = parseInt(rowStr, 10);
+      if (rowNum < atRow) return _match; // unaffected
+      const newRow = rowNum + delta;
+      if (newRow < 1) return "#REF!";
+      return `${colAbs}${colLetters}${rowAbs}${newRow}`;
+    },
+  );
+}
+
+/**
+ * Adjust formula references for column insert/delete.
+ * Shifts column references >= `atCol` by `delta`.
+ */
+export function adjustFormulaRefsForColShift(
+  formula: string,
+  atCol: number,
+  delta: number,
+): string {
+  return formula.replace(
+    /(\$?)([A-Z]+)(\$?)(\d+)/g,
+    (_match, colAbs: string, colLetters: string, rowAbs: string, rowStr: string) => {
+      const colNum = colLettersToNum(colLetters);
+      if (colNum < atCol) return _match; // unaffected
+      const newCol = colNum + delta;
+      if (newCol < 1) return "#REF!";
+      return `${colAbs}${colNumToLetters(newCol)}${rowAbs}${rowStr}`;
+    },
+  );
+}
+
+// =============================================================================
+// Paste Special
+// =============================================================================
+
+export type PasteMode = "all" | "values" | "formulas" | "formats" | "transpose";
+
+/**
+ * Paste with a specific mode:
+ * - "all" — same as regular paste (values + formulas + styles)
+ * - "values" — paste only values (no formulas, keep target formatting)
+ * - "formulas" — paste values + formulas (no styles)
+ * - "formats" — paste only styles (no values)
+ * - "transpose" — swap rows/cols (values + formulas + styles)
+ */
+export function pasteSpecial(
+  workbook: WorkbookModel,
+  clipboard: ClipboardData,
+  targetSheet: number,
+  targetRow: number,
+  targetCol: number,
+  mode: PasteMode,
+): PasteResult {
+  if (mode === "all") {
+    return pasteRange(workbook, clipboard, targetSheet, targetRow, targetCol);
+  }
+
+  const sheet = workbook.sheets[targetSheet];
+  const written: PasteResult["written"] = [];
+
+  const dRow = targetRow - clipboard.origin.row;
+  const dCol = targetCol - clipboard.origin.col;
+
+  const rowCount = mode === "transpose" ? clipboard.colCount : clipboard.rowCount;
+  const colCount = mode === "transpose" ? clipboard.rowCount : clipboard.colCount;
+
+  for (let r = 0; r < rowCount; r++) {
+    for (let c = 0; c < colCount; c++) {
+      // For transpose, swap source row/col indices
+      const srcR = mode === "transpose" ? c : r;
+      const srcC = mode === "transpose" ? r : c;
+      const src = clipboard.cells[srcR][srcC];
+
+      const ref = rowColToRef(targetRow + r, targetCol + c);
+
+      if (mode === "values") {
+        // Paste only computed values — no formulas, keep target cell's style
+        if (!src) continue;
+        const existingCell = sheet.getCell(ref);
+        const styleIndex = existingCell?.styleIndex ?? 0;
+        const numFmtCode = existingCell?.numFmtCode ?? "General";
+        sheet.set(ref, src.value, sheet.styles?.get(styleIndex), numFmtCode);
+        written.push({ ref, value: src.value, formula: undefined, styleIndex });
+      } else if (mode === "formulas") {
+        // Paste values + formulas, but keep target cell's style
+        if (!src) continue;
+        const existingCell = sheet.getCell(ref);
+        const styleIndex = existingCell?.styleIndex ?? 0;
+        const numFmtCode = existingCell?.numFmtCode ?? "General";
+        let formula = src.formula;
+        if (formula && !clipboard.isCut) {
+          formula = adjustFormulaRefs(formula, dRow, dCol);
+        }
+        sheet.set(ref, src.value, sheet.styles?.get(styleIndex), numFmtCode, formula);
+        written.push({ ref, value: src.value, formula, styleIndex });
+      } else if (mode === "formats") {
+        // Paste only styles — keep target cell's value and formula
+        if (!src) continue;
+        const existingCell = sheet.getCell(ref);
+        const value = existingCell?.value ?? null;
+        const formula = existingCell?.formula;
+        sheet.set(ref, value, sheet.styles?.get(src.styleIndex), src.numFmtCode, formula);
+        written.push({ ref, value, formula, styleIndex: src.styleIndex });
+      } else {
+        // transpose: paste everything with swapped positions + adjusted refs
+        if (!src) continue;
+        let formula = src.formula;
+        if (formula && !clipboard.isCut) {
+          // Source cell was at (origin.row + srcR, origin.col + srcC),
+          // target is (targetRow + r, targetCol + c) where r=srcC, c=srcR.
+          // Per-cell delta accounts for the transposition.
+          const srcRow = clipboard.origin.row + srcR;
+          const srcCol = clipboard.origin.col + srcC;
+          const tgtRow = targetRow + r;
+          const tgtCol = targetCol + c;
+          formula = adjustFormulaRefs(formula, tgtRow - srcRow, tgtCol - srcCol);
+        }
+        sheet.set(ref, src.value, sheet.styles?.get(src.styleIndex), src.numFmtCode, formula);
+        written.push({ ref, value: src.value, formula, styleIndex: src.styleIndex });
+      }
+    }
+  }
+
+  return { written };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+

package/src/command_history.ts

@@ -0,0 +1,102 @@
+// =============================================================================
+// Command History — Undo/Redo Stack
+// =============================================================================
+//
+// Every spreadsheet mutation flows through the command pattern:
+// - Each command knows how to execute and reverse itself
+// - CommandHistory maintains an undo/redo stack
+// - Maximum 100 entries (configurable)
+// =============================================================================
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface Command {
+  /** Human-readable description for UI display. */
+  description: string;
+  /** Execute the command (apply the change). */
+  execute(): void;
+  /** Reverse the command (undo the change). */
+  undo(): void;
+}
+
+// =============================================================================
+// CommandHistory
+// =============================================================================
+
+export class CommandHistory {
+  private undoStack: Command[] = [];
+  private redoStack: Command[] = [];
+  private maxSize: number;
+
+  constructor(maxSize = 100) {
+    this.maxSize = maxSize;
+  }
+
+  /** Execute a command and push it onto the undo stack. Clears the redo stack. */
+  execute(command: Command): void {
+    command.execute();
+    this.undoStack.push(command);
+    this.redoStack.length = 0;
+
+    // Trim undo stack if it exceeds max size
+    if (this.undoStack.length > this.maxSize) {
+      this.undoStack.shift();
+    }
+  }
+
+  /** Undo the last command. Returns the command description or undefined. */
+  undo(): string | undefined {
+    const command = this.undoStack.pop();
+    if (!command) return undefined;
+    command.undo();
+    this.redoStack.push(command);
+    return command.description;
+  }
+
+  /** Redo the last undone command. Returns the command description or undefined. */
+  redo(): string | undefined {
+    const command = this.redoStack.pop();
+    if (!command) return undefined;
+    command.execute();
+    this.undoStack.push(command);
+    return command.description;
+  }
+
+  /** Whether undo is available. */
+  get canUndo(): boolean {
+    return this.undoStack.length > 0;
+  }
+
+  /** Whether redo is available. */
+  get canRedo(): boolean {
+    return this.redoStack.length > 0;
+  }
+
+  /** Description of the next undo action. */
+  get undoDescription(): string | undefined {
+    return this.undoStack[this.undoStack.length - 1]?.description;
+  }
+
+  /** Description of the next redo action. */
+  get redoDescription(): string | undefined {
+    return this.redoStack[this.redoStack.length - 1]?.description;
+  }
+
+  /** Clear all history. */
+  clear(): void {
+    this.undoStack.length = 0;
+    this.redoStack.length = 0;
+  }
+
+  /** Number of undo entries. */
+  get undoSize(): number {
+    return this.undoStack.length;
+  }
+
+  /** Number of redo entries. */
+  get redoSize(): number {
+    return this.redoStack.length;
+  }
+}

package/src/csv_parser.test.ts

@@ -0,0 +1,130 @@
+import { parseCsvText } from "./csv_parser";
+
+describe("parseCsvText", () => {
+  test("parses basic comma-delimited CSV", () => {
+    const result = parseCsvText("Name,Age\nAlice,30\nBob,25");
+
+    expect(result.name).toBe("Sheet1");
+    expect(result.rows).toHaveLength(3);
+    expect(result.columns).toHaveLength(2);
+
+    expect(result.rows[0].cells[0].value).toBe("Name");
+    expect(result.rows[0].cells[1].value).toBe("Age");
+    expect(result.rows[1].cells[0].value).toBe("Alice");
+    expect(result.rows[1].cells[1].value).toBe("30");
+  });
+
+  test("parses tab-delimited data", () => {
+    const result = parseCsvText("Name\tAge\nAlice\t30");
+
+    expect(result.rows).toHaveLength(2);
+    expect(result.rows[0].cells[0].value).toBe("Name");
+    expect(result.rows[0].cells[1].value).toBe("Age");
+  });
+
+  test("handles quoted fields with commas", () => {
+    const result = parseCsvText('Name,Address\nAlice,"123 Main St, Apt 4"\nBob,"456 Oak Ave"');
+
+    expect(result.rows).toHaveLength(3);
+    expect(result.rows[1].cells[1].value).toBe("123 Main St, Apt 4");
+  });
+
+  test("handles escaped quotes in quoted fields", () => {
+    const result = parseCsvText('Value\n"He said ""hello"""\n"Normal"');
+
+    expect(result.rows[1].cells[0].value).toBe('He said "hello"');
+  });
+
+  test("handles multiline quoted fields", () => {
+    const result = parseCsvText('A,B\n"line1\nline2",val');
+
+    expect(result.rows).toHaveLength(2);
+    expect(result.rows[1].cells[0].value).toBe("line1\nline2");
+    expect(result.rows[1].cells[1].value).toBe("val");
+  });
+
+  test("handles \\r\\n line endings", () => {
+    const result = parseCsvText("A,B\r\n1,2\r\n3,4");
+
+    expect(result.rows).toHaveLength(3);
+    expect(result.rows[1].cells[0].value).toBe("1");
+  });
+
+  test("handles \\r line endings", () => {
+    const result = parseCsvText("A,B\r1,2\r3,4");
+
+    expect(result.rows).toHaveLength(3);
+    expect(result.rows[2].cells[0].value).toBe("3");
+  });
+
+  test("returns empty sheet for empty input", () => {
+    const result = parseCsvText("");
+
+    expect(result.rows).toHaveLength(0);
+    expect(result.columns).toHaveLength(0);
+    expect(result.totalRowCount).toBe(0);
+  });
+
+  test("returns empty sheet for whitespace-only input", () => {
+    const result = parseCsvText("   \n  ");
+
+    expect(result.rows).toHaveLength(0);
+  });
+
+  test("handles ragged rows (different column counts)", () => {
+    const result = parseCsvText("A,B,C\n1,2\n3,4,5,6");
+
+    // Column count should be based on widest row
+    expect(result.columns).toHaveLength(4);
+
+    // Short row should have empty string for missing columns
+    expect(result.rows[1].cells[2].value).toBe("");
+  });
+
+  test("computes column widths from content", () => {
+    const result = parseCsvText("ShortHeader,A much longer column header value\n1,2");
+
+    // First column: "ShortHeader" = 11 chars → 11 + 2 = 13
+    expect(result.columns[0].width).toBe(13);
+    // Second column: "A much longer column header value" = 33 chars → 33 + 2 = 35
+    expect(result.columns[1].width).toBe(35);
+  });
+
+  test("cells have no styles (plain CSV)", () => {
+    const result = parseCsvText("A\n1");
+
+    expect(result.rows[0].cells[0].style).toEqual({});
+  });
+
+  test("has no merged cells", () => {
+    const result = parseCsvText("A,B\n1,2");
+
+    expect(result.mergedCells).toHaveLength(0);
+  });
+
+  test("truncates at 10,000 rows", () => {
+    const lines = ["Col"];
+    for (let i = 0; i < 10_500; i++) {
+      lines.push(String(i));
+    }
+    const result = parseCsvText(lines.join("\n"));
+
+    expect(result.truncated).toBe(true);
+    expect(result.rows).toHaveLength(10_000);
+    expect(result.totalRowCount).toBe(10_501);
+  });
+
+  test("single column CSV", () => {
+    const result = parseCsvText("Name\nAlice\nBob");
+
+    expect(result.columns).toHaveLength(1);
+    expect(result.rows).toHaveLength(3);
+  });
+
+  test("single row CSV", () => {
+    const result = parseCsvText("A,B,C");
+
+    expect(result.rows).toHaveLength(1);
+    expect(result.rows[0].cells).toHaveLength(3);
+  });
+});