@lotics/xlsx 0.1.3 → 0.1.5

package/src/pivot_builder.test.ts

@@ -0,0 +1,278 @@
+import { describe, it, expect } from "vitest";
+import { buildDataWorkbook, type DataColumn } from "./data_workbook";
+import { SheetModel } from "./workbook_model";
+import { buildPivotTable } from "./pivot_builder";
+import { exportWorkbook } from "./xlsx_writer";
+import { unzipXlsx } from "./ooxml_zip";
+import { parseExcelBuffer } from "./excel_parser";
+import { recomputePivot, type PivotSourceData } from "./pivot_recompute";
+
+interface Row {
+  line: string;
+  size: string;
+  container: string;
+  amount: number;
+}
+
+const COLUMNS: DataColumn<Row>[] = [
+  { header: "Line", value: (r) => r.line },
+  { header: "Size", value: (r) => r.size },
+  { header: "Container", value: (r) => r.container },
+  { header: "Amount", type: "number", value: (r) => r.amount },
+];
+
+// SHA: 40HC {C1=100, C2=200}, 20DC {C3=50}; CMA: 40HC {C4=70}.
+const ROWS: Row[] = [
+  { line: "SHA", size: "40HC", container: "C1", amount: 100 },
+  { line: "SHA", size: "40HC", container: "C2", amount: 200 },
+  { line: "SHA", size: "20DC", container: "C3", amount: 50 },
+  { line: "CMA", size: "40HC", container: "C4", amount: 70 },
+];
+
+/** A workbook with a "Data" source sheet (A1:D5) + an empty "Pivot" sheet. */
+function workbookWithData() {
+  const wb = buildDataWorkbook<Row>({ sheetName: "Data", columns: COLUMNS, rows: ROWS });
+  wb.sheets.push(new SheetModel("Pivot", wb.styles));
+  return wb;
+}
+
+const decode = (b: Uint8Array) => new TextDecoder().decode(b);
+
+/** Rebuild the recompute source from the fixture (header + records). */
+function fixtureSource(): PivotSourceData {
+  return {
+    header: ["Line", "Size", "Container", "Amount"],
+    records: ROWS.map((r) => [r.line, r.size, r.container, r.amount]),
+  };
+}
+
+describe("buildPivotTable — author a native pivot", () => {
+  it("places a flagged pivot on the target sheet, sized to the result grid", () => {
+    const wb = workbookWithData();
+    const model = buildPivotTable(wb, {
+      name: "FeesByLineSize",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 3, fn: "sum", numFmtId: "3" },
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    expect(model.authored).toBe(true);
+    expect(wb.sheets[1].pivotTables).toHaveLength(1);
+    // Cache items sort lexicographically → display order: CMA,SHA / 20DC,40HC.
+    expect(model.cache.fields[0].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["CMA", "SHA"]);
+    expect(model.cache.fields[1].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["20DC", "40HC"]);
+    // Measure / unused columns carry no enumerated items.
+    expect(model.cache.fields[2].items).toEqual([]);
+    expect(model.cache.fields[3].items).toEqual([]);
+    // ref spans the grid: 2 header rows + 2 data rows + grand row = 5; 1 label col + 2 size cols + grand = 4.
+    expect(model.config.ref).toBe("A1:D5");
+  });
+
+  it("rejects fields used in more than one role and out-of-range indices", () => {
+    const wb = workbookWithData();
+    const base = {
+      name: "X",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      colField: 1,
+      data: { field: 3, fn: "sum" as const },
+      location: { sheetName: "Pivot", anchor: "A1" },
+    };
+    expect(() => buildPivotTable(wb, { ...base, rowField: 3 })).toThrow(/more than one role/);
+    expect(() => buildPivotTable(wb, { ...base, rowField: 9 })).toThrow(/out of range/);
+  });
+
+  it("fails loud on export when the source changed after build (stale cache)", () => {
+    const wb = workbookWithData();
+    buildPivotTable(wb, {
+      name: "Stale",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 3, fn: "sum" },
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    // Introduce a row-axis value the cache was not built with → encoding the
+    // records can't resolve it to a shared item, so the export must throw.
+    wb.sheets[0].set("A2", "ZZZ");
+    expect(() => exportWorkbook(wb)).toThrow(/missing from its cached shared items/);
+  });
+});
+
+describe("native pivot round-trips through the parser", () => {
+  function exportAndParse() {
+    const wb = workbookWithData();
+    buildPivotTable(wb, {
+      name: "FeesByLineSize",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 3, fn: "sum", name: "Sum of Amount", numFmtId: "3" },
+      pageFields: [],
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    const bytes = exportWorkbook(wb);
+    return { bytes, parsed: parseExcelBuffer(new Uint8Array(bytes).buffer), zip: unzipXlsx(new Uint8Array(bytes).buffer) };
+  }
+
+  it("reparses the pivot table definition (axes, data field, grand totals)", () => {
+    const { parsed } = exportAndParse();
+    const pivot = parsed.sheets.find((s) => s.name === "Pivot")?.pivotTables?.[0];
+    expect(pivot).toBeDefined();
+    expect(pivot!.name).toBe("FeesByLineSize");
+    expect(pivot!.cacheId).toBe(1);
+    expect(pivot!.rowFieldIndices).toEqual([0]);
+    expect(pivot!.colFieldIndices).toEqual([1]);
+    expect(pivot!.dataFields).toHaveLength(1);
+    // numFmtId is emitted on the dataField and round-trips (built-in 3 = #,##0).
+    expect(pivot!.dataFields[0]).toMatchObject({ fieldIndex: 3, subtotal: "sum", name: "Sum of Amount", numFmt: "3" });
+    expect(pivot!.display.rowGrandTotals).toBe(true);
+    expect(pivot!.display.colGrandTotals).toBe(true);
+    expect(pivot!.ref).toBe("A1:D5");
+  });
+
+  it("reparses the cache: worksheet source + sorted shared items + refreshOnLoad", () => {
+    const { parsed } = exportAndParse();
+    const cache = parsed.pivotCaches?.get(1);
+    expect(cache).toBeDefined();
+    expect(cache!.refreshOnLoad).toBe(true);
+    expect(cache!.source).toEqual({ type: "worksheet", sheetName: "Data", ref: "A1:D5" });
+    expect(cache!.fields.map((f) => f.name)).toEqual(["Line", "Size", "Container", "Amount"]);
+    expect(cache!.fields[0].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["CMA", "SHA"]);
+    expect(cache!.fields[1].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["20DC", "40HC"]);
+    // Measure / unused fields enumerate nothing.
+    expect(cache!.fields[2].items).toEqual([]);
+    expect(cache!.fields[3].items).toEqual([]);
+  });
+
+  it("the round-tripped definition recomputes to the correct cross-tab", () => {
+    const { parsed } = exportAndParse();
+    const pivot = parsed.sheets.find((s) => s.name === "Pivot")!.pivotTables![0];
+    const cache = parsed.pivotCaches!.get(1)!;
+    const grid = recomputePivot(pivot, cache, fixtureSource());
+
+    // Header rows then body. rowLabelCols = 1; data cols = 2 (20DC, 40HC) + grand.
+    const valueAt = (r: number, c: number) => {
+      const cell = grid.cells[r][c];
+      return cell.kind === "value" || cell.kind === "rowTotal" || cell.kind === "colTotal" || cell.kind === "grandTotal"
+        ? cell.value
+        : undefined;
+    };
+    // Row order CMA, SHA after the header rows.
+    const hdr = grid.headerRows;
+    // CMA row: 20DC empty (sum of no records = 0 in the engine), 40HC 70, rowTotal 70.
+    expect(valueAt(hdr, 1)).toBe(0); // CMA × 20DC
+    expect(valueAt(hdr, 2)).toBe(70); // CMA × 40HC
+    expect(valueAt(hdr, 3)).toBe(70); // CMA row total
+    // SHA row: 20DC 50, 40HC 300, rowTotal 350.
+    expect(valueAt(hdr + 1, 1)).toBe(50);
+    expect(valueAt(hdr + 1, 2)).toBe(300);
+    expect(valueAt(hdr + 1, 3)).toBe(350);
+    // Grand row: 20DC 50, 40HC 370, grand 420.
+    expect(valueAt(hdr + 2, 1)).toBe(50);
+    expect(valueAt(hdr + 2, 2)).toBe(370);
+    expect(valueAt(hdr + 2, 3)).toBe(420);
+  });
+
+  it("encodes cache records as shared-item indices (axis) + inline values (measure)", () => {
+    const { zip } = exportAndParse();
+    const records = decode(zip["xl/pivotCache/pivotCacheRecords1.xml"]);
+    expect(records).toContain('count="4"');
+    // First fixture row SHA(idx1)/40HC(idx1)/C1/100 → indices for the two axis
+    // fields, then inline string + inline number.
+    expect(records).toContain('<r><x v="1"/><x v="1"/><s v="C1"/><n v="100"/></r>');
+    // CMA(idx0)/40HC(idx1)/C4/70.
+    expect(records).toContain('<r><x v="0"/><x v="1"/><s v="C4"/><n v="70"/></r>');
+  });
+
+  it("registers content-types, workbook pivotCaches, and the full rels chain", () => {
+    const { zip } = exportAndParse();
+    const ct = decode(zip["[Content_Types].xml"]);
+    expect(ct).toContain("/xl/pivotTables/pivotTable1.xml");
+    expect(ct).toContain("/xl/pivotCache/pivotCacheDefinition1.xml");
+    expect(ct).toContain("/xl/pivotCache/pivotCacheRecords1.xml");
+
+    const wb = decode(zip["xl/workbook.xml"]);
+    expect(wb).toContain("<pivotCaches>");
+    expect(wb).toMatch(/<pivotCache cacheId="1" r:id="rId\d+"\/>/);
+
+    expect(decode(zip["xl/_rels/workbook.xml.rels"])).toContain("pivotCache/pivotCacheDefinition1.xml");
+    // The Pivot sheet (sheet 2) rels → its pivot table.
+    expect(decode(zip["xl/worksheets/_rels/sheet2.xml.rels"])).toContain("../pivotTables/pivotTable1.xml");
+    // pivotTable → cacheDefinition, cacheDefinition → records.
+    expect(decode(zip["xl/pivotTables/_rels/pivotTable1.xml.rels"])).toContain("../pivotCache/pivotCacheDefinition1.xml");
+    expect(decode(zip["xl/pivotCache/_rels/pivotCacheDefinition1.xml.rels"])).toContain("pivotCacheRecords1.xml");
+  });
+
+  it("the exported workbook re-parses without error and keeps the data sheet", () => {
+    const { parsed } = exportAndParse();
+    expect(parsed.sheets.map((s) => s.name)).toEqual(["Data", "Pivot"]);
+    // The source data survived alongside the new pivot parts.
+    const data = parsed.sheets[0];
+    const a1 = data.rows.find((r) => r.index === 1)?.cells.find((c) => c.column === 1);
+    expect(a1?.value).toBe("Line");
+  });
+});
+
+describe("page filter + count aggregation", () => {
+  it("round-trips a page (report-filter) field", () => {
+    const wb = workbookWithData();
+    buildPivotTable(wb, {
+      name: "Filtered",
+      source: { sheetName: "Data", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 3, fn: "sum" },
+      pageFields: [2], // Container as a report filter
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    const bytes = exportWorkbook(wb);
+    const parsed = parseExcelBuffer(new Uint8Array(bytes).buffer);
+    const pivot = parsed.sheets[1].pivotTables![0];
+    expect(pivot.pageFieldIndices).toEqual([2]);
+    // The page field is enumerated like an axis field (it filters on items).
+    const cache = parsed.pivotCaches!.get(1)!;
+    expect(cache.fields[2].items.map((i) => (i.kind === "string" ? i.value : i.kind))).toEqual(["C1", "C2", "C3", "C4"]);
+  });
+
+  it("Count over a distinct-container roster reproduces distinct counts", () => {
+    // The app's distinct-count pivot pattern: a roster with ONE row per distinct
+    // container; COUNT of the container column = distinct container count.
+    const roster: Row[] = [
+      { line: "SHA", size: "40HC", container: "C1", amount: 0 },
+      { line: "SHA", size: "40HC", container: "C2", amount: 0 },
+      { line: "SHA", size: "20DC", container: "C3", amount: 0 },
+      { line: "CMA", size: "40HC", container: "C4", amount: 0 },
+    ];
+    const wb = buildDataWorkbook<Row>({ sheetName: "Roster", columns: COLUMNS, rows: roster });
+    wb.sheets.push(new SheetModel("Pivot", wb.styles));
+    buildPivotTable(wb, {
+      name: "ContainersByLineSize",
+      source: { sheetName: "Roster", ref: "A1:D5" },
+      rowField: 0,
+      colField: 1,
+      data: { field: 2, fn: "count" }, // count of Container
+      location: { sheetName: "Pivot", anchor: "A1" },
+    });
+    const bytes = exportWorkbook(wb);
+    const parsed = parseExcelBuffer(new Uint8Array(bytes).buffer);
+    const pivot = parsed.sheets[1].pivotTables![0];
+    const cache = parsed.pivotCaches!.get(1)!;
+    const grid = recomputePivot(pivot, cache, {
+      header: ["Line", "Size", "Container", "Amount"],
+      records: roster.map((r) => [r.line, r.size, r.container, r.amount]),
+    });
+    const hdr = grid.headerRows;
+    const num = (r: number, c: number) => {
+      const cell = grid.cells[r][c];
+      return "value" in cell ? cell.value : undefined;
+    };
+    // SHA row (second, after CMA): 20DC=1, 40HC=2, total 3.
+    expect(num(hdr + 1, 1)).toBe(1);
+    expect(num(hdr + 1, 2)).toBe(2);
+    expect(num(hdr + 1, 3)).toBe(3);
+    // Grand row: total distinct containers = 4.
+    expect(num(hdr + 2, 3)).toBe(4);
+    expect(pivot.dataFields[0].subtotal).toBe("count");
+  });
+});

package/src/pivot_builder.ts

@@ -0,0 +1,187 @@
+// =============================================================================
+// Pivot Table Builder
+// =============================================================================
+//
+// Authors a native Excel PivotTable from scratch over a worksheet range. The
+// returned model is attached to the target sheet (`sheet.pivotTables`) and
+// flagged `authored`, so `exportWorkbook` serializes it into real OOXML pivot
+// parts (see `pivot_writer.ts`).
+//
+// v1 shape (the 2D cross-tab): exactly one row field, one column field, one
+// data field, and zero or more page (report-filter) fields. The shared-item
+// order in the cache is the SAME String()-lexicographic order `pivot_recompute`
+// uses to lay out rows/columns, so the saved item indices line up with the
+// displayed order — no remapping needed in the writer.
+// =============================================================================
+
+import type { WorkbookModel } from "./workbook_model";
+import type {
+  ParsedPivotCache,
+  ParsedPivotTable,
+  PivotAggregateFn,
+  PivotCacheField,
+  PivotCacheItem,
+  PivotFieldConfig,
+} from "./ooxml_pivot_types";
+import { PivotTableModel, readSourceData } from "./pivot_model";
+import { recomputePivot, type PivotSourceData } from "./pivot_recompute";
+import { sourceValueToItem, cacheItemKey, cacheItemSortKey } from "./pivot_writer";
+import { refToRowCol, rowColToRef } from "./excel_utils";
+
+export interface PivotBuildSpec {
+  /** Pivot table name — must be unique within the workbook. */
+  name: string;
+  /** Source data range: a sheet + a range whose first row is the header. */
+  source: { sheetName: string; ref: string };
+  /** Source column index (0-based within the range) for the row axis. */
+  rowField: number;
+  /** Source column index for the column axis. */
+  colField: number;
+  /**
+   * The value field placed on the data axis. `numFmtId` is a BUILT-IN Excel
+   * number-format id (e.g. "3" = `#,##0`), not a format code — a custom code
+   * (`'#,##0" ₫"'`) would need a registered style, which v1 does not wire up.
+   */
+  data: { field: number; fn?: PivotAggregateFn; name?: string; numFmtId?: string };
+  /** Source column indices used as report (page) filters. Default none. */
+  pageFields?: number[];
+  /** Where the pivot is placed: a sheet + the top-left anchor cell. */
+  location: { sheetName: string; anchor: string };
+  /** Show the grand-total column (per-row totals). Default true. */
+  rowGrandTotals?: boolean;
+  /** Show the grand-total row (per-column totals). Default true. */
+  colGrandTotals?: boolean;
+  /** Table style name. Default "PivotStyleLight16". */
+  styleName?: string;
+}
+
+const AGG_VERB: Record<PivotAggregateFn, string> = {
+  sum: "Sum",
+  count: "Count",
+  countNums: "Count",
+  average: "Average",
+  min: "Min",
+  max: "Max",
+  product: "Product",
+};
+
+export function buildPivotTable(workbook: WorkbookModel, spec: PivotBuildSpec): PivotTableModel {
+  const target = workbook.sheets.find((s) => s.name === spec.location.sheetName);
+  if (!target) throw new Error(`buildPivotTable: target sheet "${spec.location.sheetName}" not found`);
+
+  // Read the source range. A minimal cache carries only the source coordinates;
+  // `readSourceData` reads header + records straight from the worksheet.
+  const cacheSource = { type: "worksheet" as const, sheetName: spec.source.sheetName, ref: spec.source.ref };
+  const source = readSourceData(workbook, { id: 0, source: cacheSource, fields: [], refreshOnLoad: true });
+  if (!source) throw new Error(`buildPivotTable: source range "${spec.source.ref}" on "${spec.source.sheetName}" not found`);
+
+  const fieldCount = source.header.length;
+  const pageFields = spec.pageFields ?? [];
+  validateSpec(spec, fieldCount, pageFields);
+
+  // Assign a cache id one past the highest existing pivot cache (so authored and
+  // any round-tripped pivots never collide).
+  const existing = workbook.sheets.flatMap((s) => s.pivotTables);
+  const cacheId = existing.reduce((max, p) => Math.max(max, p.cache.id), 0) + 1;
+
+  const axisFields = new Set([spec.rowField, spec.colField, ...pageFields]);
+  const cacheFields: PivotCacheField[] = source.header.map((name, i) => buildCacheField(name, i, source, axisFields.has(i)));
+  const cache: ParsedPivotCache = { id: cacheId, source: cacheSource, fields: cacheFields, refreshOnLoad: true };
+
+  const fn = spec.data.fn ?? "sum";
+  const config: ParsedPivotTable = {
+    name: spec.name,
+    cacheId,
+    ref: "A1:A1", // sized after recompute
+    firstHeaderRow: 1,
+    firstDataRow: 1,
+    firstDataCol: 1,
+    fields: buildFieldConfigs(fieldCount, spec, pageFields),
+    rowFieldIndices: [spec.rowField],
+    colFieldIndices: [spec.colField],
+    pageFieldIndices: pageFields,
+    dataFields: [
+      {
+        name: spec.data.name ?? `${AGG_VERB[fn]} of ${source.header[spec.data.field] || `field ${spec.data.field}`}`,
+        fieldIndex: spec.data.field,
+        subtotal: fn,
+        numFmt: spec.data.numFmtId,
+      },
+    ],
+    styleName: spec.styleName ?? "PivotStyleLight16",
+    display: {
+      rowGrandTotals: spec.rowGrandTotals ?? true,
+      colGrandTotals: spec.colGrandTotals ?? true,
+      showRowStripes: false,
+      showColStripes: false,
+    },
+  };
+
+  // Recompute to size the location ref and the data-offset hints. The result
+  // also seeds `model.result` so a caller can render without a second pass.
+  const grid = recomputePivot(config, cache, source);
+  const anchor = refToRowCol(spec.location.anchor);
+  if (!anchor) throw new Error(`buildPivotTable: invalid anchor "${spec.location.anchor}"`);
+  config.ref = `${spec.location.anchor}:${rowColToRef(anchor.row + grid.rows - 1, anchor.col + grid.cols - 1)}`;
+  config.firstHeaderRow = 1;
+  config.firstDataRow = grid.headerRows;
+  config.firstDataCol = grid.rowLabelCols;
+
+  const model = new PivotTableModel(config, cache, true);
+  model.result = grid;
+  target.pivotTables.push(model);
+  return model;
+}
+
+function validateSpec(spec: PivotBuildSpec, fieldCount: number, pageFields: number[]): void {
+  const inRange = (i: number) => Number.isInteger(i) && i >= 0 && i < fieldCount;
+  if (!inRange(spec.rowField)) throw new Error(`buildPivotTable: rowField ${spec.rowField} out of range (0..${fieldCount - 1})`);
+  if (!inRange(spec.colField)) throw new Error(`buildPivotTable: colField ${spec.colField} out of range (0..${fieldCount - 1})`);
+  if (!inRange(spec.data.field)) throw new Error(`buildPivotTable: data.field ${spec.data.field} out of range (0..${fieldCount - 1})`);
+  for (const p of pageFields) if (!inRange(p)) throw new Error(`buildPivotTable: pageField ${p} out of range (0..${fieldCount - 1})`);
+  const roles = [spec.rowField, spec.colField, spec.data.field, ...pageFields];
+  if (new Set(roles).size !== roles.length) {
+    throw new Error("buildPivotTable: a field cannot be used in more than one role (row/column/data/page)");
+  }
+}
+
+/** Distinct, display-sorted shared items for an axis field; type hints only for
+ *  a measure/unused column (its values inline into the cache records). */
+function buildCacheField(name: string, col: number, source: PivotSourceData, enumerate: boolean): PivotCacheField {
+  const containsNumber = source.records.some((rec) => typeof rec[col] === "number");
+  const containsDate = false;
+  if (!enumerate) return { name, items: [], numFmt: undefined, containsNumber, containsDate };
+
+  const seen = new Set<string>();
+  const items: PivotCacheItem[] = [];
+  for (const rec of source.records) {
+    const item = sourceValueToItem(rec[col]);
+    const key = cacheItemKey(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    items.push(item);
+  }
+  items.sort((a, b) => {
+    const as = cacheItemSortKey(a);
+    const bs = cacheItemSortKey(b);
+    return as < bs ? -1 : as > bs ? 1 : 0;
+  });
+  return { name, items, numFmt: undefined, containsNumber, containsDate };
+}
+
+function buildFieldConfigs(fieldCount: number, spec: PivotBuildSpec, pageFields: number[]): PivotFieldConfig[] {
+  const pageSet = new Set(pageFields);
+  const out: PivotFieldConfig[] = [];
+  for (let i = 0; i < fieldCount; i++) {
+    const axis =
+      i === spec.rowField ? "row" : i === spec.colField ? "column" : pageSet.has(i) ? "page" : i === spec.data.field ? "values" : undefined;
+    out.push({
+      axis,
+      showSubtotal: true,
+      compact: true,
+      showAll: false,
+      selectedPageItem: pageSet.has(i) ? null : undefined,
+    });
+  }
+  return out;
+}

package/src/pivot_model.ts

@@ -30,10 +30,18 @@ export class PivotTableModel {
   cache: ParsedPivotCache;
   /** Last computed result, or undefined before first recompute. */
   result: PivotResultGrid | undefined;
+  /**
+   * True when this pivot was authored from scratch (via `buildPivotTable`) and
+   * must be SERIALIZED by the writer into fresh OOXML parts. Parsed pivots leave
+   * this false — they round-trip verbatim from the original zip, so the writer
+   * skips them. The writer keys emission on this flag.
+   */
+  authored: boolean;
 
-  constructor(config: ParsedPivotTable, cache: ParsedPivotCache) {
+  constructor(config: ParsedPivotTable, cache: ParsedPivotCache, authored = false) {
     this.config = config;
     this.cache = cache;
+    this.authored = authored;
   }
 
   /**