@lotics/xlsx 0.1.0

package/src/pivot_recompute.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect } from "vitest";
+import { aggregate, recomputePivot } from "./pivot_recompute";
+import type { PivotSourceData } from "./pivot_recompute";
+import type {
+  ParsedPivotCache,
+  ParsedPivotTable,
+} from "./ooxml_pivot_types";
+
+// =============================================================================
+// Aggregate
+// =============================================================================
+
+describe("aggregate", () => {
+  it("sums numbers, ignoring strings", () => {
+    expect(aggregate([1, 2, "x", 3], "sum")).toBe(6);
+  });
+
+  it("counts non-blank values, including strings", () => {
+    expect(aggregate([1, "x", null, 2, undefined, ""], "count")).toBe(3);
+  });
+
+  it("countNums only counts numeric", () => {
+    expect(aggregate([1, "x", null, 2], "countNums")).toBe(2);
+  });
+
+  it("average over numeric values, null when no numbers", () => {
+    expect(aggregate([2, 4, 6], "average")).toBe(4);
+    expect(aggregate(["x", null], "average")).toBeNull();
+  });
+
+  it("min/max/product over numeric values", () => {
+    expect(aggregate([5, 1, 3], "min")).toBe(1);
+    expect(aggregate([5, 1, 3], "max")).toBe(5);
+    expect(aggregate([2, 3, 4], "product")).toBe(24);
+  });
+});
+
+// =============================================================================
+// Fixtures
+// =============================================================================
+
+const SOURCE: PivotSourceData = {
+  header: ["Region", "Quarter", "Revenue"],
+  records: [
+    ["North", "Q1", 100],
+    ["North", "Q2", 200],
+    ["South", "Q1", 50],
+    ["South", "Q2", 75],
+  ],
+};
+
+function makeTable(overrides: Partial<ParsedPivotTable> = {}): ParsedPivotTable {
+  return {
+    name: "Test",
+    cacheId: 1,
+    ref: "A3:E12",
+    firstHeaderRow: 0,
+    firstDataCol: 1,
+    firstDataRow: 2,
+    fields: [
+      { showSubtotal: true, compact: true, showAll: false },
+      { showSubtotal: true, compact: true, showAll: false },
+      { showSubtotal: true, compact: true, showAll: false },
+    ],
+    rowFieldIndices: [0],
+    colFieldIndices: [1],
+    pageFieldIndices: [],
+    dataFields: [
+      { name: "Sum of Revenue", fieldIndex: 2, subtotal: "sum" },
+    ],
+    display: {
+      rowGrandTotals: true,
+      colGrandTotals: true,
+      showRowStripes: false,
+      showColStripes: false,
+    },
+    ...overrides,
+  };
+}
+
+const CACHE: ParsedPivotCache = {
+  id: 1,
+  source: { type: "worksheet", sheetName: "Data", ref: "A1:C5" },
+  fields: [
+    {
+      name: "Region",
+      items: [
+        { kind: "string", value: "North" },
+        { kind: "string", value: "South" },
+      ],
+      containsNumber: false,
+      containsDate: false,
+    },
+    {
+      name: "Quarter",
+      items: [
+        { kind: "string", value: "Q1" },
+        { kind: "string", value: "Q2" },
+      ],
+      containsNumber: false,
+      containsDate: false,
+    },
+    {
+      name: "Revenue",
+      items: [],
+      containsNumber: true,
+      containsDate: false,
+    },
+  ],
+  refreshOnLoad: false,
+};
+
+// =============================================================================
+// Recompute
+// =============================================================================
+
+describe("recomputePivot", () => {
+  it("produces a 4x5 grid for two row tuples × two col tuples + grand totals + label", () => {
+    const grid = recomputePivot(makeTable(), CACHE, SOURCE);
+    // 1 row label col + 2 col tuples + 1 grand total col = 4 cols
+    expect(grid.cols).toBe(4);
+    // 1 col-axis header row + 1 value-label row + 2 row tuples + 1 grand total = 5 rows
+    expect(grid.rows).toBe(5);
+    expect(grid.headerRows).toBe(2);
+    expect(grid.rowLabelCols).toBe(1);
+  });
+
+  it("places col-axis labels in row 0", () => {
+    const grid = recomputePivot(makeTable(), CACHE, SOURCE);
+    expect(grid.cells[0][1]).toMatchObject({ kind: "colHeader", text: "Q1" });
+    expect(grid.cells[0][2]).toMatchObject({ kind: "colHeader", text: "Q2" });
+  });
+
+  it("computes body sums correctly", () => {
+    const grid = recomputePivot(makeTable(), CACHE, SOURCE);
+    // Row 2 (after 2 header rows) is "North". Col 1 = Q1 → 100. Col 2 = Q2 → 200.
+    expect(grid.cells[2][0]).toMatchObject({ kind: "rowHeader", text: "North" });
+    expect(grid.cells[2][1]).toMatchObject({ kind: "value", value: 100 });
+    expect(grid.cells[2][2]).toMatchObject({ kind: "value", value: 200 });
+  });
+
+  it("computes per-row grand totals", () => {
+    const grid = recomputePivot(makeTable(), CACHE, SOURCE);
+    expect(grid.cells[2][3]).toMatchObject({ kind: "rowTotal", value: 300 }); // North Q1+Q2
+    expect(grid.cells[3][3]).toMatchObject({ kind: "rowTotal", value: 125 }); // South
+  });
+
+  it("computes column grand totals", () => {
+    const grid = recomputePivot(makeTable(), CACHE, SOURCE);
+    const lastRow = grid.rows - 1;
+    expect(grid.cells[lastRow][0]).toMatchObject({
+      kind: "totalLabel",
+      text: "Grand Total",
+    });
+    expect(grid.cells[lastRow][1]).toMatchObject({ kind: "colTotal", value: 150 }); // Q1
+    expect(grid.cells[lastRow][2]).toMatchObject({ kind: "colTotal", value: 275 }); // Q2
+    expect(grid.cells[lastRow][3]).toMatchObject({ kind: "grandTotal", value: 425 });
+  });
+
+  it("filters by page-axis selection", () => {
+    const filtered = makeTable({
+      pageFieldIndices: [0],
+      fields: [
+        { showSubtotal: true, compact: true, showAll: false, selectedPageItem: 0 }, // North only
+        { showSubtotal: true, compact: true, showAll: false },
+        { showSubtotal: true, compact: true, showAll: false },
+      ],
+      rowFieldIndices: [],
+      colFieldIndices: [1],
+    });
+    const grid = recomputePivot(filtered, CACHE, SOURCE);
+    // Grand total of just the North rows = 300
+    expect(grid.cells[grid.rows - 1].at(-1)).toMatchObject({
+      kind: "grandTotal",
+      value: 300,
+    });
+  });
+
+  it("handles multiple data fields side-by-side under each col tuple", () => {
+    const t = makeTable({
+      dataFields: [
+        { name: "Sum", fieldIndex: 2, subtotal: "sum" },
+        { name: "Count", fieldIndex: 2, subtotal: "count" },
+      ],
+    });
+    const grid = recomputePivot(t, CACHE, SOURCE);
+    // 1 row-label + 2 col tuples × 2 data fields + 2 grand-total cols = 7
+    expect(grid.cols).toBe(7);
+    // Value-label row places "Sum" then "Count" repeating
+    const labelRow = grid.headerRows - 1;
+    expect(grid.cells[labelRow][1]).toMatchObject({ kind: "valueLabel", text: "Sum" });
+    expect(grid.cells[labelRow][2]).toMatchObject({ kind: "valueLabel", text: "Count" });
+    expect(grid.cells[labelRow][3]).toMatchObject({ kind: "valueLabel", text: "Sum" });
+    expect(grid.cells[labelRow][4]).toMatchObject({ kind: "valueLabel", text: "Count" });
+  });
+
+  it("respects display flags: turning off grand totals shrinks the grid", () => {
+    const t = makeTable({
+      display: {
+        rowGrandTotals: false,
+        colGrandTotals: false,
+        showRowStripes: false,
+        showColStripes: false,
+      },
+    });
+    const grid = recomputePivot(t, CACHE, SOURCE);
+    expect(grid.cols).toBe(3); // row label + 2 col tuples, no col grand
+    expect(grid.rows).toBe(4); // 2 headers + 2 row tuples, no grand row
+  });
+});

package/src/pivot_recompute.ts

@@ -0,0 +1,413 @@
+// =============================================================================
+// Pivot Recompute
+// =============================================================================
+//
+// Pure aggregation: given a parsed source range and a pivot configuration,
+// produce a 2D result grid the renderer can paint inside the pivot's `ref`.
+//
+// Design choices:
+//   - Multi-level row & column axes: each axis tuple is a list of cell values
+//     in axis order. Grouping is by JSON-stringified tuple.
+//   - Stable sort by tuple — ties broken alphabetically so tests are
+//     deterministic and the layout is human-readable.
+//   - Page-axis filter: a field with `selectedPageItem` set drops every record
+//     whose value at that field index doesn't match the selected cache item.
+//   - Grand totals: appended unconditionally when the model says so. A grand
+//     total cell aggregates over *all* records in the corresponding stripe.
+//   - Empty output: when a group/value combination has no records, the cell
+//     is `null`; the renderer can paint blank (matches Excel's default).
+// =============================================================================
+
+import type {
+  ParsedPivotCache,
+  ParsedPivotTable,
+  PivotAggregateFn,
+  PivotCacheItem,
+} from "./ooxml_pivot_types";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * A single source record indexed by cache-field position. `undefined` for a
+ * missing/empty cell. Numeric strings are pre-coerced to numbers when the
+ * cache field declares `containsNumber` so aggregations Just Work.
+ */
+export type PivotSourceRecord = (string | number | boolean | null | undefined)[];
+
+/**
+ * The shape the recompute engine needs from the source range.
+ * `header[i]` is the column header text for cache field `i`.
+ */
+export interface PivotSourceData {
+  header: string[];
+  records: PivotSourceRecord[];
+}
+
+/**
+ * One cell in the layout grid. `kind` carries semantic context for styling
+ * decisions (banding, header bold, totals row).
+ */
+export type PivotResultCell =
+  | { kind: "blank" }
+  | { kind: "rowHeader"; depth: number; text: string }
+  | { kind: "colHeader"; depth: number; text: string }
+  | { kind: "valueLabel"; text: string }
+  | { kind: "value"; value: number | null; numFmt?: string }
+  | { kind: "rowTotal"; value: number | null }
+  | { kind: "colTotal"; value: number | null }
+  | { kind: "grandTotal"; value: number | null }
+  | { kind: "totalLabel"; text: string };
+
+/** 2D grid with row 0 at top, column 0 at left. */
+export interface PivotResultGrid {
+  /** [rowIndex][colIndex] */
+  cells: PivotResultCell[][];
+  /** Number of header rows at the top (for renderer banding logic). */
+  headerRows: number;
+  /** Number of row-label columns on the left. */
+  rowLabelCols: number;
+  /** Computed row count, columns. */
+  rows: number;
+  cols: number;
+}
+
+// =============================================================================
+// Recompute
+// =============================================================================
+
+const TOTAL_LABEL = "Grand Total";
+
+export function recomputePivot(
+  table: ParsedPivotTable,
+  cache: ParsedPivotCache,
+  source: PivotSourceData,
+): PivotResultGrid {
+  const records = filterByPageAxis(table, cache, source.records);
+
+  const rowTuples = distinctTuples(records, table.rowFieldIndices);
+  const colTuples = distinctTuples(records, table.colFieldIndices);
+
+  // Group records by (rowTuple, colTuple).
+  const groupKey = (rec: PivotSourceRecord) =>
+    JSON.stringify([
+      tupleOf(rec, table.rowFieldIndices),
+      tupleOf(rec, table.colFieldIndices),
+    ]);
+  const groups = new Map<string, PivotSourceRecord[]>();
+  for (const rec of records) {
+    const key = groupKey(rec);
+    let bucket = groups.get(key);
+    if (!bucket) {
+      bucket = [];
+      groups.set(key, bucket);
+    }
+    bucket.push(rec);
+  }
+
+  return buildGrid(table, source, rowTuples, colTuples, groups, records);
+}
+
+// =============================================================================
+// Page filter
+// =============================================================================
+
+function filterByPageAxis(
+  table: ParsedPivotTable,
+  cache: ParsedPivotCache,
+  records: PivotSourceRecord[],
+): PivotSourceRecord[] {
+  const filters: { fieldIndex: number; allowed: PivotCacheItem }[] = [];
+  for (const fi of table.pageFieldIndices) {
+    const cfg = table.fields[fi];
+    if (cfg?.selectedPageItem == null) continue;
+    const cacheField = cache.fields[fi];
+    if (!cacheField) continue;
+    const allowed = cacheField.items[cfg.selectedPageItem];
+    if (allowed) filters.push({ fieldIndex: fi, allowed });
+  }
+  if (filters.length === 0) return records;
+
+  return records.filter((rec) =>
+    filters.every(({ fieldIndex, allowed }) =>
+      cellMatchesItem(rec[fieldIndex], allowed),
+    ),
+  );
+}
+
+function cellMatchesItem(
+  cell: PivotSourceRecord[number],
+  item: PivotCacheItem,
+): boolean {
+  switch (item.kind) {
+    case "string":
+      return typeof cell === "string" && cell === item.value;
+    case "number":
+      return typeof cell === "number" && cell === item.value;
+    case "boolean":
+      return typeof cell === "boolean" && cell === item.value;
+    case "date":
+      return typeof cell === "string" && cell === item.value;
+    case "missing":
+      return cell === undefined || cell === null || cell === "";
+    case "error":
+      return typeof cell === "string" && cell === item.value;
+  }
+}
+
+// =============================================================================
+// Tuple helpers
+// =============================================================================
+
+function tupleOf(
+  rec: PivotSourceRecord,
+  indices: number[],
+): PivotSourceRecord {
+  return indices.map((i) => rec[i] ?? null);
+}
+
+function distinctTuples(
+  records: PivotSourceRecord[],
+  indices: number[],
+): PivotSourceRecord[] {
+  const seen = new Set<string>();
+  const out: PivotSourceRecord[] = [];
+  for (const rec of records) {
+    const t = tupleOf(rec, indices);
+    const key = JSON.stringify(t);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+  }
+  // Stable lexicographic sort: numeric values stringify in the form "123",
+  // strings as "\"abc\"". Side effect: numbers sort by string order in mixed
+  // tuples — acceptable for v1 since real-world axes are usually homogeneous.
+  out.sort((a, b) => {
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+      const av = a[i];
+      const bv = b[i];
+      if (av === bv) continue;
+      const as = av === null || av === undefined ? "" : String(av);
+      const bs = bv === null || bv === undefined ? "" : String(bv);
+      if (as < bs) return -1;
+      if (as > bs) return 1;
+    }
+    return 0;
+  });
+  return out;
+}
+
+// =============================================================================
+// Aggregation
+// =============================================================================
+
+export function aggregate(
+  values: (string | number | boolean | null | undefined)[],
+  fn: PivotAggregateFn,
+): number | null {
+  const numeric = values.filter((v): v is number => typeof v === "number");
+  switch (fn) {
+    case "count":
+      return values.filter((v) => v !== null && v !== undefined && v !== "").length;
+    case "countNums":
+      return numeric.length;
+    case "sum":
+      return numeric.reduce((a, b) => a + b, 0);
+    case "average":
+      if (numeric.length === 0) return null;
+      return numeric.reduce((a, b) => a + b, 0) / numeric.length;
+    case "min":
+      return numeric.length === 0 ? null : Math.min(...numeric);
+    case "max":
+      return numeric.length === 0 ? null : Math.max(...numeric);
+    case "product":
+      return numeric.length === 0 ? null : numeric.reduce((a, b) => a * b, 1);
+  }
+}
+
+// =============================================================================
+// Grid builder
+// =============================================================================
+
+function buildGrid(
+  table: ParsedPivotTable,
+  source: PivotSourceData,
+  rowTuples: PivotSourceRecord[],
+  colTuples: PivotSourceRecord[],
+  groups: Map<string, PivotSourceRecord[]>,
+  allRecords: PivotSourceRecord[],
+): PivotResultGrid {
+  const numRowFields = table.rowFieldIndices.length;
+  const numColFields = table.colFieldIndices.length;
+  const numDataFields = Math.max(table.dataFields.length, 1);
+  const showRowGrand = table.display.colGrandTotals; // bottom row labelled "row grand"
+  const showColGrand = table.display.rowGrandTotals; // rightmost col labelled "col grand"
+
+  // Layout dimensions
+  const rowLabelCols = Math.max(numRowFields, 1);
+  // One header row per column-axis level. When there are data fields, one
+  // additional header row labels each value column. When there are no
+  // column-axis fields, the value-label row is the only header row.
+  const colHeaderRows = numColFields + (numDataFields > 0 ? 1 : 0);
+  const headerRows = Math.max(colHeaderRows, 1);
+
+  const dataCols = colTuples.length * numDataFields;
+  const totalCols = rowLabelCols + dataCols + (showColGrand ? numDataFields : 0);
+  const totalRows = headerRows + rowTuples.length + (showRowGrand ? 1 : 0);
+
+  const cells: PivotResultCell[][] = [];
+  for (let r = 0; r < totalRows; r++) {
+    cells.push(new Array(totalCols).fill({ kind: "blank" }));
+  }
+
+  // ---- Column headers ------------------------------------------------------
+  for (let level = 0; level < numColFields; level++) {
+    let col = rowLabelCols;
+    for (const tuple of colTuples) {
+      const text = formatCellLabel(tuple[level]);
+      for (let i = 0; i < numDataFields; i++) {
+        cells[level][col + i] = { kind: "colHeader", depth: level, text };
+      }
+      col += numDataFields;
+    }
+  }
+
+  // Data-field labels row (always present when there is at least one)
+  if (numDataFields > 0) {
+    const labelRow = colHeaderRows - 1;
+    let col = rowLabelCols;
+    for (let _t = 0; _t < colTuples.length; _t++) {
+      for (let d = 0; d < table.dataFields.length; d++) {
+        cells[labelRow][col + d] = {
+          kind: "valueLabel",
+          text: table.dataFields[d].name,
+        };
+      }
+      col += numDataFields;
+    }
+    if (showColGrand) {
+      for (let d = 0; d < table.dataFields.length; d++) {
+        cells[labelRow][rowLabelCols + dataCols + d] = {
+          kind: "valueLabel",
+          text: table.dataFields[d].name,
+        };
+      }
+    }
+  }
+
+  // ---- Row headers + body --------------------------------------------------
+  for (let r = 0; r < rowTuples.length; r++) {
+    const rowTuple = rowTuples[r];
+    const gridRow = headerRows + r;
+
+    for (let level = 0; level < numRowFields; level++) {
+      cells[gridRow][level] = {
+        kind: "rowHeader",
+        depth: level,
+        text: formatCellLabel(rowTuple[level]),
+      };
+    }
+
+    // Body cells
+    for (let c = 0; c < colTuples.length; c++) {
+      const colTuple = colTuples[c];
+      const groupRecords =
+        groups.get(JSON.stringify([rowTuple, colTuple])) ?? [];
+      for (let d = 0; d < table.dataFields.length; d++) {
+        const df = table.dataFields[d];
+        const values = groupRecords.map((rec) => rec[df.fieldIndex]);
+        cells[gridRow][rowLabelCols + c * numDataFields + d] = {
+          kind: "value",
+          value: aggregate(values, df.subtotal),
+          numFmt: df.numFmt,
+        };
+      }
+    }
+
+    // Per-row grand total (across all column tuples)
+    if (showColGrand) {
+      const rowOnly = allRecords.filter((rec) =>
+        sameTuple(tupleOf(rec, table.rowFieldIndices), rowTuple),
+      );
+      for (let d = 0; d < table.dataFields.length; d++) {
+        const df = table.dataFields[d];
+        cells[gridRow][rowLabelCols + dataCols + d] = {
+          kind: "rowTotal",
+          value: aggregate(
+            rowOnly.map((rec) => rec[df.fieldIndex]),
+            df.subtotal,
+          ),
+        };
+      }
+    }
+  }
+
+  // ---- Grand total row -----------------------------------------------------
+  if (showRowGrand) {
+    const gridRow = headerRows + rowTuples.length;
+    cells[gridRow][0] = { kind: "totalLabel", text: TOTAL_LABEL };
+
+    for (let c = 0; c < colTuples.length; c++) {
+      const colTuple = colTuples[c];
+      const colOnly = allRecords.filter((rec) =>
+        sameTuple(tupleOf(rec, table.colFieldIndices), colTuple),
+      );
+      for (let d = 0; d < table.dataFields.length; d++) {
+        const df = table.dataFields[d];
+        cells[gridRow][rowLabelCols + c * numDataFields + d] = {
+          kind: "colTotal",
+          value: aggregate(
+            colOnly.map((rec) => rec[df.fieldIndex]),
+            df.subtotal,
+          ),
+        };
+      }
+    }
+
+    if (showColGrand) {
+      for (let d = 0; d < table.dataFields.length; d++) {
+        const df = table.dataFields[d];
+        cells[gridRow][rowLabelCols + dataCols + d] = {
+          kind: "grandTotal",
+          value: aggregate(
+            allRecords.map((rec) => rec[df.fieldIndex]),
+            df.subtotal,
+          ),
+        };
+      }
+    }
+  }
+
+  // Trim labels for empty header areas — touch is cosmetic; renderer treats
+  // {kind: "blank"} as nothing, so leaving them is also fine.
+  void source;
+
+  return {
+    cells,
+    headerRows,
+    rowLabelCols,
+    rows: totalRows,
+    cols: totalCols,
+  };
+}
+
+function sameTuple(a: PivotSourceRecord, b: PivotSourceRecord): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      // Treat null/undefined/empty-string as equal: Excel collapses them on
+      // pivot row/col axes.
+      const an = a[i] === undefined || a[i] === null || a[i] === "";
+      const bn = b[i] === undefined || b[i] === null || b[i] === "";
+      if (!(an && bn)) return false;
+    }
+  }
+  return true;
+}
+
+function formatCellLabel(v: PivotSourceRecord[number]): string {
+  if (v === undefined || v === null || v === "") return "(blank)";
+  if (typeof v === "boolean") return v ? "TRUE" : "FALSE";
+  return String(v);
+}