@lotics/xlsx 0.1.0

package/src/structured_refs.test.ts

@@ -0,0 +1,128 @@
+import { expandStructuredRefs } from "./structured_refs";
+import type { ParsedTable } from "./ooxml_chart_types";
+
+function makeTable(overrides: Partial<ParsedTable> = {}): ParsedTable {
+  return {
+    name: "Sales",
+    displayName: "Sales",
+    ref: "B2:D10",
+    columns: [{ name: "Product" }, { name: "Revenue" }, { name: "Qty" }],
+    headerRow: true,
+    totalsRow: false,
+    styleName: "TableStyleMedium9",
+    ...overrides,
+  };
+}
+
+describe("expandStructuredRefs", () => {
+  test("returns formula unchanged when no tables exist", () => {
+    expect(expandStructuredRefs("SUM(A1:A10)", [], 5)).toBe("SUM(A1:A10)");
+  });
+
+  test("returns formula unchanged when no structured refs present", () => {
+    const tables = [makeTable()];
+    expect(expandStructuredRefs("A1+B2", tables, 5)).toBe("A1+B2");
+  });
+
+  test("expands TableName[ColumnName] to data body range", () => {
+    const tables = [makeTable()];
+    // Table B2:D10, header=true, no totals → data is rows 3-10
+    // "Revenue" is column index 1 → column C
+    const result = expandStructuredRefs("SUM(Sales[Revenue])", tables, 5);
+    expect(result).toBe("SUM(C3:C10)");
+  });
+
+  test("expands TableName[ColumnName] with totals row", () => {
+    const tables = [makeTable({ totalsRow: true })];
+    // With totals: data is rows 3-9 (last row reserved for totals)
+    const result = expandStructuredRefs("SUM(Sales[Revenue])", tables, 5);
+    expect(result).toBe("SUM(C3:C9)");
+  });
+
+  test("expands TableName[ColumnName] without header row", () => {
+    const tables = [makeTable({ headerRow: false })];
+    // No header: data starts at row 2
+    const result = expandStructuredRefs("SUM(Sales[Revenue])", tables, 5);
+    expect(result).toBe("SUM(C2:C10)");
+  });
+
+  test("expands [@ColumnName] to this-row reference", () => {
+    const tables = [makeTable()];
+    const result = expandStructuredRefs("[@Revenue]*[@Qty]", tables, 5);
+    // Revenue → col C, Qty → col D, row 5
+    expect(result).toBe("C5*D5");
+  });
+
+  test("expands [#Data] to entire data body", () => {
+    const tables = [makeTable()];
+    const result = expandStructuredRefs("SUM(Sales[#Data])", tables, 5);
+    expect(result).toBe("SUM(B3:D10)");
+  });
+
+  test("expands [#Headers] to header row", () => {
+    const tables = [makeTable()];
+    const result = expandStructuredRefs("Sales[#Headers]", tables, 5);
+    expect(result).toBe("B2:D2");
+  });
+
+  test("returns unchanged for [#Headers] when no header row", () => {
+    const tables = [makeTable({ headerRow: false })];
+    const result = expandStructuredRefs("Sales[#Headers]", tables, 5);
+    expect(result).toBe("Sales[#Headers]");
+  });
+
+  test("expands [#Totals] to totals row", () => {
+    const tables = [makeTable({ totalsRow: true })];
+    const result = expandStructuredRefs("Sales[#Totals]", tables, 5);
+    expect(result).toBe("B10:D10");
+  });
+
+  test("expands [[#Headers],[ColumnName]]", () => {
+    const tables = [makeTable()];
+    const result = expandStructuredRefs("Sales[[#Headers],[Revenue]]", tables, 5);
+    expect(result).toBe("C2");
+  });
+
+  test("expands [[#Totals],[ColumnName]]", () => {
+    const tables = [makeTable({ totalsRow: true })];
+    const result = expandStructuredRefs("Sales[[#Totals],[Revenue]]", tables, 5);
+    expect(result).toBe("C10");
+  });
+
+  test("case-insensitive column matching", () => {
+    const tables = [makeTable()];
+    const result = expandStructuredRefs("SUM(Sales[revenue])", tables, 5);
+    expect(result).toBe("SUM(C3:C10)");
+  });
+
+  test("matches by displayName", () => {
+    const tables = [makeTable({ name: "tbl1", displayName: "Sales" })];
+    const result = expandStructuredRefs("SUM(Sales[Revenue])", tables, 5);
+    expect(result).toBe("SUM(C3:C10)");
+  });
+
+  test("returns unchanged for unknown table name", () => {
+    const tables = [makeTable()];
+    const result = expandStructuredRefs("SUM(Other[Revenue])", tables, 5);
+    expect(result).toBe("SUM(Other[Revenue])");
+  });
+
+  test("returns unchanged for unknown column name", () => {
+    const tables = [makeTable()];
+    const result = expandStructuredRefs("SUM(Sales[Nonexistent])", tables, 5);
+    expect(result).toBe("SUM(Sales[Nonexistent])");
+  });
+
+  test("handles multiple structured refs in one formula", () => {
+    const tables = [makeTable()];
+    const result = expandStructuredRefs("Sales[Revenue]+Sales[Qty]", tables, 5);
+    expect(result).toBe("C3:C10+D3:D10");
+  });
+
+  test("first column resolves correctly", () => {
+    const tables = [makeTable()];
+    const result = expandStructuredRefs("SUM(Sales[Product])", tables, 5);
+    // Product is column index 0 → column B
+    expect(result).toBe("SUM(B3:B10)");
+  });
+});

package/src/structured_refs.ts

@@ -0,0 +1,160 @@
+// =============================================================================
+// Structured Reference Expansion
+// =============================================================================
+//
+// Expands Excel structured table references into cell range references.
+// Patterns:
+//   TableName[ColumnName]              → data body column range
+//   TableName[[#Headers],[ColumnName]] → header cell
+//   TableName[[#Totals],[ColumnName]]  → totals cell
+//   TableName[#Data]                   → entire data body
+//   [@ColumnName]                      → this-row reference (needs context)
+// =============================================================================
+
+import type { ParsedTable } from "./ooxml_chart_types";
+import { colLettersToNum, colNumToLetters } from "./excel_utils";
+
+/**
+ * Expand structured references in a formula, replacing them with A1-style ranges.
+ * @param formula  Raw formula string (without leading =)
+ * @param tables   Tables from the sheet model
+ * @param currentRow  The row of the cell containing the formula (for @ references)
+ */
+export function expandStructuredRefs(
+  formula: string,
+  tables: ParsedTable[],
+  currentRow: number,
+): string {
+  if (tables.length === 0) return formula;
+
+  // Match patterns like TableName[...] or [@ColumnName]
+  // The inner bracket group uses [^\[\]]* to avoid consuming nested brackets
+  return formula.replace(
+    /(\w+)?\[((?:[^[\]]*(?:\[[^\]]*\])?)*)\]/g,
+    (match, tableName: string | undefined, bracketContent: string) => {
+      // Handle [@ColumnName] — bare this-row reference without table name
+      if (!tableName && bracketContent.startsWith("@")) {
+        const colName = bracketContent.slice(1);
+        const table = findTableForColumn(tables, colName);
+        if (!table) return match;
+        return resolveThisRow(table, colName, currentRow);
+      }
+
+      if (!tableName) return match;
+
+      const table = tables.find(
+        (t) => t.name === tableName || t.displayName === tableName,
+      );
+      if (!table) return match;
+
+      return resolveStructuredRef(table, bracketContent, currentRow) ?? match;
+    },
+  );
+}
+
+function resolveStructuredRef(
+  table: ParsedTable,
+  content: string,
+  currentRow: number,
+): string | undefined {
+  const { ref, columns, headerRow, totalsRow } = table;
+  const range = parseTableRange(ref);
+  if (!range) return undefined;
+
+  // [#Data] — entire data body
+  if (content === "#Data" || content === "#All") {
+    const dataStartRow = headerRow ? range.startRow + 1 : range.startRow;
+    const dataEndRow = totalsRow ? range.endRow - 1 : range.endRow;
+    return `${colNumToLetters(range.startCol)}${dataStartRow}:${colNumToLetters(range.endCol)}${dataEndRow}`;
+  }
+
+  // [#Headers] — entire header row
+  if (content === "#Headers") {
+    if (!headerRow) return undefined;
+    return `${colNumToLetters(range.startCol)}${range.startRow}:${colNumToLetters(range.endCol)}${range.startRow}`;
+  }
+
+  // [#Totals] — entire totals row
+  if (content === "#Totals") {
+    if (!totalsRow) return undefined;
+    return `${colNumToLetters(range.startCol)}${range.endRow}:${colNumToLetters(range.endCol)}${range.endRow}`;
+  }
+
+  // [[#Headers],[ColumnName]]
+  const headerMatch = content.match(/^\[#Headers\],\s*\[?([^\]]+)\]?$/);
+  if (headerMatch && headerRow) {
+    const colIndex = findColumnIndex(columns, headerMatch[1]);
+    if (colIndex < 0) return undefined;
+    const col = range.startCol + colIndex;
+    return `${colNumToLetters(col)}${range.startRow}`;
+  }
+
+  // [[#Totals],[ColumnName]]
+  const totalsMatch = content.match(/^\[#Totals\],\s*\[?([^\]]+)\]?$/);
+  if (totalsMatch && totalsRow) {
+    const colIndex = findColumnIndex(columns, totalsMatch[1]);
+    if (colIndex < 0) return undefined;
+    const col = range.startCol + colIndex;
+    return `${colNumToLetters(col)}${range.endRow}`;
+  }
+
+  // [@ColumnName] — this-row reference within table context
+  if (content.startsWith("@")) {
+    const colName = content.slice(1).replace(/^\[|\]$/g, "");
+    return resolveThisRow(table, colName, currentRow);
+  }
+
+  // [ColumnName] — data body column range
+  const colName = content.replace(/^\[|\]$/g, "");
+  const colIndex = findColumnIndex(columns, colName);
+  if (colIndex < 0) return undefined;
+
+  const col = range.startCol + colIndex;
+  const dataStartRow = headerRow ? range.startRow + 1 : range.startRow;
+  const dataEndRow = totalsRow ? range.endRow - 1 : range.endRow;
+  return `${colNumToLetters(col)}${dataStartRow}:${colNumToLetters(col)}${dataEndRow}`;
+}
+
+function resolveThisRow(
+  table: ParsedTable,
+  colName: string,
+  currentRow: number,
+): string {
+  const range = parseTableRange(table.ref);
+  if (!range) return colName;
+
+  const colIndex = findColumnIndex(table.columns, colName);
+  if (colIndex < 0) return colName;
+
+  const col = range.startCol + colIndex;
+  return `${colNumToLetters(col)}${currentRow}`;
+}
+
+function findTableForColumn(
+  tables: ParsedTable[],
+  colName: string,
+): ParsedTable | undefined {
+  return tables.find((t) => findColumnIndex(t.columns, colName) >= 0);
+}
+
+function findColumnIndex(
+  columns: { name: string }[],
+  name: string,
+): number {
+  return columns.findIndex(
+    (c) => c.name.toLowerCase() === name.toLowerCase(),
+  );
+}
+
+function parseTableRange(
+  ref: string,
+): { startRow: number; startCol: number; endRow: number; endCol: number } | undefined {
+  const match = ref.match(/^([A-Z]+)(\d+):([A-Z]+)(\d+)$/);
+  if (!match) return undefined;
+  return {
+    startCol: colLettersToNum(match[1]),
+    startRow: parseInt(match[2], 10),
+    endCol: colLettersToNum(match[3]),
+    endRow: parseInt(match[4], 10),
+  };
+}

package/src/style_helpers.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest";
+import { allBorders, bottomBorder, topBorder } from "./style_helpers";
+
+describe("allBorders", () => {
+  it("returns thin black borders by default", () => {
+    const b = allBorders();
+    expect(b.borderTop).toEqual({ width: 1, style: "thin", color: "#000000" });
+    expect(b.borderRight).toEqual({ width: 1, style: "thin", color: "#000000" });
+    expect(b.borderBottom).toEqual({ width: 1, style: "thin", color: "#000000" });
+    expect(b.borderLeft).toEqual({ width: 1, style: "thin", color: "#000000" });
+  });
+
+  it("accepts custom style and color", () => {
+    const b = allBorders("medium", "#4472C4");
+    expect(b.borderTop).toEqual({ width: 1, style: "medium", color: "#4472C4" });
+  });
+});
+
+describe("bottomBorder", () => {
+  it("returns medium black bottom border by default", () => {
+    const b = bottomBorder();
+    expect(b.borderBottom).toEqual({ width: 1, style: "medium", color: "#000000" });
+    expect(b).not.toHaveProperty("borderTop");
+  });
+});
+
+describe("topBorder", () => {
+  it("returns medium black top border by default", () => {
+    const b = topBorder();
+    expect(b.borderTop).toEqual({ width: 1, style: "medium", color: "#000000" });
+    expect(b).not.toHaveProperty("borderBottom");
+  });
+});

package/src/style_helpers.ts

@@ -0,0 +1,30 @@
+import type { CellStyle, BorderStyle } from "./types";
+
+function border(style = "thin", color = "#000000"): BorderStyle {
+  return { width: 1, style, color };
+}
+
+/** Thin black borders on all four sides. */
+export function allBorders(
+  style = "thin",
+  color = "#000000",
+): Pick<CellStyle, "borderTop" | "borderRight" | "borderBottom" | "borderLeft"> {
+  const b = border(style, color);
+  return { borderTop: b, borderRight: b, borderBottom: b, borderLeft: b };
+}
+
+/** Single bottom border. */
+export function bottomBorder(
+  style = "medium",
+  color = "#000000",
+): Pick<CellStyle, "borderBottom"> {
+  return { borderBottom: border(style, color) };
+}
+
+/** Single top border. */
+export function topBorder(
+  style = "medium",
+  color = "#000000",
+): Pick<CellStyle, "borderTop"> {
+  return { borderTop: border(style, color) };
+}

package/src/template_builder.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect } from "vitest";
+import { buildTemplateWorkbook } from "./template_builder";
+import { allBorders } from "./style_helpers";
+import { exportWorkbook } from "./xlsx_writer";
+
+describe("buildTemplateWorkbook", () => {
+  it("builds a single-sheet workbook with set()", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.set("A1", "Hello");
+      sheet.set("B1", 42);
+    });
+
+    expect(wb.sheets).toHaveLength(1);
+    expect(wb.sheets[0].getCell("A1")?.value).toBe("Hello");
+    expect(wb.sheets[0].getCell("B1")?.value).toBe(42);
+  });
+
+  it("interns styles via set()", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.set("A1", "Bold", { fontBold: true });
+      sheet.set("A2", "Also Bold", { fontBold: true });
+    });
+
+    const a1 = wb.sheets[0].getCell("A1")!;
+    const a2 = wb.sheets[0].getCell("A2")!;
+    expect(a1.styleIndex).toBe(a2.styleIndex);
+    expect(a1.styleIndex).toBeGreaterThan(0);
+  });
+
+  it("set() uses numFmt parameter", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.set("A1", 1500, { horizontalAlign: "right" }, "#,##0.00");
+    });
+
+    const cell = wb.sheets[0].getCell("A1")!;
+    expect(cell.numFmtCode).toBe("#,##0.00");
+    expect(cell.displayValue).toBe("1,500.00");
+  });
+
+  it("set() defaults to styleIndex 0 and General numFmt", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.set("A1", "plain");
+    });
+
+    const cell = wb.sheets[0].getCell("A1")!;
+    expect(cell.styleIndex).toBe(0);
+    expect(cell.numFmtCode).toBe("General");
+  });
+
+  it("merge() adds range and sets top-left value", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.merge("A1:C1", "Title", { fontBold: true, fontSize: 14 });
+    });
+
+    expect(wb.sheets[0].mergedCells).toContain("A1:C1");
+    expect(wb.sheets[0].getCell("A1")?.value).toBe("Title");
+    expect(wb.sheets[0].getCell("A1")?.styleIndex).toBeGreaterThan(0);
+  });
+
+  it("merge() without value just adds the range", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.merge("A1:C1");
+    });
+
+    expect(wb.sheets[0].mergedCells).toContain("A1:C1");
+    expect(wb.sheets[0].getCell("A1")).toBeUndefined();
+  });
+
+  it("setColumnWidth() accepts letter or index", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.setColumnWidth("A", 30);
+      sheet.setColumnWidth(2, 20); // index 2 = column B
+    });
+
+    expect(wb.sheets[0].colWidths.get(1)).toBe(30); // "A" → 1
+    expect(wb.sheets[0].colWidths.get(2)).toBe(20);
+  });
+
+  it("setRowHeight() sets height", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.setRowHeight(1, 25);
+    });
+
+    expect(wb.sheets[0].rowHeights.get(1)).toBe(25);
+  });
+
+  it("headerRow() writes bold bordered cells with background", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.headerRow(1, ["Name", "Amount", "Date"]);
+    });
+
+    const sheet = wb.sheets[0];
+    expect(sheet.getCell("A1")?.value).toBe("Name");
+    expect(sheet.getCell("B1")?.value).toBe("Amount");
+    expect(sheet.getCell("C1")?.value).toBe("Date");
+
+    const style = wb.styles.get(sheet.getCell("A1")!.styleIndex);
+    expect(style.fontBold).toBe(true);
+    expect(style.horizontalAlign).toBe("center");
+    expect(style.backgroundColor).toBe("#D9E1F2");
+    expect(style.borderTop).toBeDefined();
+  });
+
+  it("headerRow() accepts custom background", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.headerRow(1, ["A"], { background: "#E2EFDA" });
+    });
+
+    const style = wb.styles.get(wb.sheets[0].getCell("A1")!.styleIndex);
+    expect(style.backgroundColor).toBe("#E2EFDA");
+  });
+
+  it("builds multi-sheet workbook", () => {
+    const wb = buildTemplateWorkbook(
+      { name: "Summary", build: (s) => s.set("A1", "Summary") },
+      { name: "Details", build: (s) => s.set("A1", "Details") },
+    );
+
+    expect(wb.sheets).toHaveLength(2);
+    expect(wb.sheets[0].name).toBe("Summary");
+    expect(wb.sheets[1].name).toBe("Details");
+    expect(wb.sheets[0].getCell("A1")?.value).toBe("Summary");
+    expect(wb.sheets[1].getCell("A1")?.value).toBe("Details");
+  });
+
+  it("exports to valid xlsx", () => {
+    const wb = buildTemplateWorkbook((sheet) => {
+      sheet.merge("A1:B1", "Header", { fontBold: true });
+      sheet.headerRow(2, ["Col A", "Col B"]);
+      sheet.set("A3", "data", { ...allBorders() });
+      sheet.set("B3", 100, { horizontalAlign: "right", ...allBorders() }, "#,##0.00");
+      sheet.setColumnWidth("A", 25);
+      sheet.setColumnWidth("B", 15);
+    });
+
+    const bytes = exportWorkbook(wb);
+    expect(bytes.byteLength).toBeGreaterThan(0);
+  });
+});

package/src/template_builder.ts

@@ -0,0 +1,36 @@
+import { WorkbookModel, SheetModel, StyleRegistry } from "./workbook_model";
+
+interface SheetDef {
+  name: string;
+  build: (sheet: SheetModel) => void;
+}
+
+/**
+ * Build a template workbook.
+ * Single-sheet: `buildTemplateWorkbook((sheet) => { ... })`
+ * Multi-sheet: `buildTemplateWorkbook({ name: "A", build: (s) => {} }, { name: "B", build: (s) => {} })`
+ */
+export function buildTemplateWorkbook(
+  ...args: [(sheet: SheetModel) => void] | SheetDef[]
+): WorkbookModel {
+  const styles = new StyleRegistry();
+
+  if (args.length === 1 && typeof args[0] === "function") {
+    const sheet = new SheetModel("Sheet1", styles);
+    args[0](sheet);
+    return new WorkbookModel({ sheets: [sheet], activeSheetIndex: 0, styles });
+  }
+
+  const sheetDefs = args as SheetDef[];
+  const sheets = sheetDefs.map((def) => {
+    const sheet = new SheetModel(def.name, styles);
+    def.build(sheet);
+    return sheet;
+  });
+
+  return new WorkbookModel({
+    sheets: sheets.length > 0 ? sheets : [new SheetModel("Sheet1", styles)],
+    activeSheetIndex: 0,
+    styles,
+  });
+}